1 /*******************************************************************************
2 * Copyright (c) 2010, 2016 Ericsson, École Polytechnique de Montréal, and others
4 * All rights reserved. This program and the accompanying materials are
5 * made available under the terms of the Eclipse Public License v1.0 which
6 * accompanies this distribution, and is available at
7 * http://www.eclipse.org/legal/epl-v10.html
10 * Alexandre Montplaisir - Initial API and implementation
11 * Florian Wininger - Add Extension and Leaf Node
12 * Patrick Tasse - Add message to exceptions
13 *******************************************************************************/
15 package org
.eclipse
.tracecompass
.internal
.statesystem
.core
.backend
.historytree
;
18 import java
.io
.FileInputStream
;
19 import java
.io
.IOException
;
20 import java
.io
.PrintWriter
;
21 import java
.nio
.ByteBuffer
;
22 import java
.nio
.ByteOrder
;
23 import java
.nio
.channels
.ClosedChannelException
;
24 import java
.nio
.channels
.FileChannel
;
25 import java
.util
.ArrayList
;
26 import java
.util
.Collections
;
27 import java
.util
.List
;
29 import org
.eclipse
.jdt
.annotation
.NonNull
;
30 import org
.eclipse
.tracecompass
.internal
.statesystem
.core
.Activator
;
31 import org
.eclipse
.tracecompass
.statesystem
.core
.ITmfStateSystemBuilder
;
32 import org
.eclipse
.tracecompass
.statesystem
.core
.exceptions
.TimeRangeException
;
34 import com
.google
.common
.annotations
.VisibleForTesting
;
35 import com
.google
.common
.collect
.ImmutableList
;
38 * Meta-container for the History Tree. This structure contains all the
39 * high-level data relevant to the tree.
41 * @author Alexandre Montplaisir
43 public class HistoryTreeClassic
implements IHistoryTree
{
46 * The magic number for this file format. Package-private for the factory
49 static final int HISTORY_FILE_MAGIC_NUMBER
= 0x05FFA900;
51 /** File format version. Increment when breaking compatibility. */
52 private static final int FILE_VERSION
= 7;
54 // ------------------------------------------------------------------------
55 // Tree-specific configuration
56 // ------------------------------------------------------------------------
58 /** Container for all the configuration constants */
59 private final HTConfig fConfig
;
61 /** Reader/writer object */
62 private final HT_IO fTreeIO
;
64 // ------------------------------------------------------------------------
65 // Variable Fields (will change throughout the existence of the SHT)
66 // ------------------------------------------------------------------------
68 /** Latest timestamp found in the tree (at any given moment) */
69 private long fTreeEnd
;
71 /** The total number of nodes that exists in this tree */
72 private int fNodeCount
;
74 /** "Cache" to keep the active nodes in memory */
75 private final @NonNull List
<@NonNull HTNode
> fLatestBranch
;
77 // ------------------------------------------------------------------------
78 // Constructors/"Destructors"
79 // ------------------------------------------------------------------------
82 * Create a new State History from scratch, using a {@link HTConfig} object
86 * The config to use for this History Tree.
88 * If an error happens trying to open/write to the file
89 * specified in the config
91 public HistoryTreeClassic(HTConfig conf
) throws IOException
{
93 * Simple check to make sure we have enough place in the 0th block for
94 * the tree configuration
96 if (conf
.getBlockSize() < TREE_HEADER_SIZE
) {
97 throw new IllegalArgumentException();
101 fTreeEnd
= conf
.getTreeStart();
103 fLatestBranch
= Collections
.synchronizedList(new ArrayList
<>());
105 /* Prepare the IO object */
106 fTreeIO
= new HT_IO(fConfig
, true);
108 /* Add the first node to the tree */
109 LeafNode firstNode
= initNewLeafNode(-1, conf
.getTreeStart());
110 fLatestBranch
.add(firstNode
);
114 * "Reader" constructor : instantiate a SHTree from an existing tree file on
117 * @param existingStateFile
118 * Path/filename of the history-file we are to open
119 * @param expProviderVersion
120 * The expected version of the state provider
121 * @throws IOException
122 * If an error happens reading the file
124 public HistoryTreeClassic(File existingStateFile
, int expProviderVersion
) throws IOException
{
126 * Open the file ourselves, get the tree header information we need,
127 * then pass on the descriptor to the TreeIO object.
129 int rootNodeSeqNb
, res
;
133 /* Java I/O mumbo jumbo... */
134 if (!existingStateFile
.exists()) {
135 throw new IOException("Selected state file does not exist"); //$NON-NLS-1$
137 if (existingStateFile
.length() <= 0) {
138 throw new IOException("Empty target file"); //$NON-NLS-1$
141 try (FileInputStream fis
= new FileInputStream(existingStateFile
);
142 FileChannel fc
= fis
.getChannel();) {
144 ByteBuffer buffer
= ByteBuffer
.allocate(TREE_HEADER_SIZE
);
146 buffer
.order(ByteOrder
.LITTLE_ENDIAN
);
152 * Check the magic number to make sure we're opening the right type
155 res
= buffer
.getInt();
156 if (res
!= HISTORY_FILE_MAGIC_NUMBER
) {
157 throw new IOException("Wrong magic number"); //$NON-NLS-1$
160 res
= buffer
.getInt(); /* File format version number */
161 if (res
!= FILE_VERSION
) {
162 throw new IOException("Mismatching History Tree file format versions"); //$NON-NLS-1$
165 res
= buffer
.getInt(); /* Event handler's version number */
166 if (res
!= expProviderVersion
&&
167 expProviderVersion
!= ITmfStateSystemBuilder
.IGNORE_PROVIDER_VERSION
) {
169 * The existing history was built using an event handler that
170 * doesn't match the current one in the framework.
172 * Information could be all wrong. Instead of keeping an
173 * incorrect history file, a rebuild is done.
175 throw new IOException("Mismatching event handler versions"); //$NON-NLS-1$
178 bs
= buffer
.getInt(); /* Block Size */
179 maxc
= buffer
.getInt(); /* Max nb of children per node */
181 fNodeCount
= buffer
.getInt();
182 rootNodeSeqNb
= buffer
.getInt();
183 startTime
= buffer
.getLong();
185 fConfig
= new HTConfig(existingStateFile
, bs
, maxc
, expProviderVersion
, startTime
);
189 * FIXME We close fis here and the TreeIO will then reopen the same
190 * file, not extremely elegant. But how to pass the information here to
193 fTreeIO
= new HT_IO(fConfig
, false);
195 fLatestBranch
= buildLatestBranch(rootNodeSeqNb
);
196 fTreeEnd
= getRootNode().getNodeEnd();
199 * Make sure the history start time we read previously is consistent
200 * with was is actually in the root node.
202 if (startTime
!= getRootNode().getNodeStart()) {
203 throw new IOException("Inconsistent start times in the" + //$NON-NLS-1$
204 "history file, it might be corrupted."); //$NON-NLS-1$
209 * Rebuild the latestBranch "cache" object by reading the nodes from disk
210 * (When we are opening an existing file on disk and want to append to it,
213 * @param rootNodeSeqNb
214 * The sequence number of the root node, so we know where to
216 * @throws ClosedChannelException
218 private @NonNull List
<@NonNull HTNode
> buildLatestBranch(int rootNodeSeqNb
) throws ClosedChannelException
{
219 List
<@NonNull HTNode
> list
= new ArrayList
<>();
221 HTNode nextChildNode
= fTreeIO
.readNode(rootNodeSeqNb
);
222 list
.add(nextChildNode
);
224 /* Follow the last branch up to the leaf */
225 while (nextChildNode
.getNodeType() == HTNode
.NodeType
.CORE
) {
226 nextChildNode
= fTreeIO
.readNode(((CoreNode
) nextChildNode
).getLatestChild());
227 list
.add(nextChildNode
);
229 return Collections
.synchronizedList(list
);
233 public void closeTree(long requestedEndTime
) {
234 /* This is an important operation, queries can wait */
235 synchronized (fLatestBranch
) {
237 * Work-around the "empty branches" that get created when the root
238 * node becomes full. Overwrite the tree's end time with the
239 * original wanted end-time, to ensure no queries are sent into
242 * This won't be needed once extended nodes are implemented.
244 fTreeEnd
= requestedEndTime
;
246 /* Close off the latest branch of the tree */
247 for (int i
= 0; i
< fLatestBranch
.size(); i
++) {
248 fLatestBranch
.get(i
).closeThisNode(fTreeEnd
);
249 fTreeIO
.writeNode(fLatestBranch
.get(i
));
252 try (FileChannel fc
= fTreeIO
.getFcOut();) {
253 ByteBuffer buffer
= ByteBuffer
.allocate(TREE_HEADER_SIZE
);
254 buffer
.order(ByteOrder
.LITTLE_ENDIAN
);
257 /* Save the config of the tree to the header of the file */
260 buffer
.putInt(HISTORY_FILE_MAGIC_NUMBER
);
262 buffer
.putInt(FILE_VERSION
);
263 buffer
.putInt(fConfig
.getProviderVersion());
265 buffer
.putInt(fConfig
.getBlockSize());
266 buffer
.putInt(fConfig
.getMaxChildren());
268 buffer
.putInt(fNodeCount
);
270 /* root node seq. nb */
271 buffer
.putInt(fLatestBranch
.get(0).getSequenceNumber());
273 /* start time of this history */
274 buffer
.putLong(fLatestBranch
.get(0).getNodeStart());
277 int res
= fc
.write(buffer
);
278 assert (res
<= TREE_HEADER_SIZE
);
279 /* done writing the file header */
281 } catch (IOException e
) {
283 * If we were able to write so far, there should not be any
284 * problem at this point...
286 throw new RuntimeException("State system write error"); //$NON-NLS-1$
291 // ------------------------------------------------------------------------
293 // ------------------------------------------------------------------------
296 public long getTreeStart() {
297 return fConfig
.getTreeStart();
301 public long getTreeEnd() {
306 public int getNodeCount() {
311 public HTNode
getRootNode() {
312 return fLatestBranch
.get(0);
316 * Return the latest branch of the tree. That branch is immutable. Used for
317 * unit testing and debugging.
319 * @return The immutable latest branch
322 protected List
<@NonNull HTNode
> getLatestBranch() {
323 return ImmutableList
.copyOf(fLatestBranch
);
327 * Read a node at sequence number
330 * The sequence number of the node to read
331 * @return The HTNode object
332 * @throws ClosedChannelException
333 * Exception thrown when reading the node
336 protected @NonNull HTNode
getNode(int seqNum
) throws ClosedChannelException
{
337 // First, check in the latest branch if the node is there
338 for (HTNode node
: fLatestBranch
) {
339 if (node
.getSequenceNumber() == seqNum
) {
343 return fTreeIO
.readNode(seqNum
);
346 // ------------------------------------------------------------------------
348 // ------------------------------------------------------------------------
351 public FileInputStream
supplyATReader() {
352 return fTreeIO
.supplyATReader(getNodeCount());
356 public File
supplyATWriterFile() {
357 return fConfig
.getStateFile();
361 public long supplyATWriterFilePos() {
362 return IHistoryTree
.TREE_HEADER_SIZE
363 + ((long) getNodeCount() * fConfig
.getBlockSize());
367 public HTNode
readNode(int seqNumber
) throws ClosedChannelException
{
368 /* Try to read the node from memory */
369 synchronized (fLatestBranch
) {
370 for (HTNode node
: fLatestBranch
) {
371 if (node
.getSequenceNumber() == seqNumber
) {
377 /* Read the node from disk */
378 return fTreeIO
.readNode(seqNumber
);
382 public void writeNode(HTNode node
) {
383 fTreeIO
.writeNode(node
);
387 public void closeFile() {
392 public void deleteFile() {
393 fTreeIO
.deleteFile();
396 // ------------------------------------------------------------------------
398 // ------------------------------------------------------------------------
401 public void insertInterval(HTInterval interval
) throws TimeRangeException
{
402 if (interval
.getStartTime() < fConfig
.getTreeStart()) {
403 throw new TimeRangeException("Interval Start:" + interval
.getStartTime() + ", Config Start:" + fConfig
.getTreeStart()); //$NON-NLS-1$ //$NON-NLS-2$
405 tryInsertAtNode(interval
, fLatestBranch
.size() - 1);
409 * Inner method to find in which node we should add the interval.
412 * The interval to add to the tree
414 * The index *in the latestBranch* where we are trying the
417 private void tryInsertAtNode(HTInterval interval
, int indexOfNode
) {
418 HTNode targetNode
= fLatestBranch
.get(indexOfNode
);
420 /* Verify if there is enough room in this node to store this interval */
421 if (interval
.getSizeOnDisk() > targetNode
.getNodeFreeSpace()) {
422 /* Nope, not enough room. Insert in a new sibling instead. */
423 addSiblingNode(indexOfNode
);
424 tryInsertAtNode(interval
, fLatestBranch
.size() - 1);
428 /* Make sure the interval time range fits this node */
429 if (interval
.getStartTime() < targetNode
.getNodeStart()) {
431 * No, this interval starts before the startTime of this node. We
432 * need to check recursively in parents if it can fit.
434 tryInsertAtNode(interval
, indexOfNode
- 1);
439 * Ok, there is room, and the interval fits in this time slot. Let's add
442 targetNode
.addInterval(interval
);
444 /* Update treeEnd if needed */
445 if (interval
.getEndTime() > fTreeEnd
) {
446 fTreeEnd
= interval
.getEndTime();
451 * Method to add a sibling to any node in the latest branch. This will add
452 * children back down to the leaf level, if needed.
455 * The index in latestBranch where we start adding
457 private void addSiblingNode(int indexOfNode
) {
458 synchronized (fLatestBranch
) {
459 final long splitTime
= fTreeEnd
;
461 if (indexOfNode
>= fLatestBranch
.size()) {
463 * We need to make sure (indexOfNode - 1) doesn't get the last
464 * node in the branch, because that one is a Leaf Node.
466 throw new IllegalStateException();
469 /* Check if we need to add a new root node */
470 if (indexOfNode
== 0) {
475 /* Check if we can indeed add a child to the target parent */
476 if (((CoreNode
) fLatestBranch
.get(indexOfNode
- 1)).getNbChildren() == fConfig
.getMaxChildren()) {
477 /* If not, add a branch starting one level higher instead */
478 addSiblingNode(indexOfNode
- 1);
482 /* Split off the new branch from the old one */
483 for (int i
= indexOfNode
; i
< fLatestBranch
.size(); i
++) {
484 fLatestBranch
.get(i
).closeThisNode(splitTime
);
485 fTreeIO
.writeNode(fLatestBranch
.get(i
));
487 CoreNode prevNode
= (CoreNode
) fLatestBranch
.get(i
- 1);
490 switch (fLatestBranch
.get(i
).getNodeType()) {
492 newNode
= initNewCoreNode(prevNode
.getSequenceNumber(), splitTime
+ 1);
495 newNode
= initNewLeafNode(prevNode
.getSequenceNumber(), splitTime
+ 1);
498 throw new IllegalStateException();
501 prevNode
.linkNewChild(newNode
);
502 fLatestBranch
.set(i
, newNode
);
508 * Similar to the previous method, except here we rebuild a completely new
511 private void addNewRootNode() {
512 final long splitTime
= fTreeEnd
;
514 HTNode oldRootNode
= fLatestBranch
.get(0);
515 CoreNode newRootNode
= initNewCoreNode(-1, fConfig
.getTreeStart());
517 /* Tell the old root node that it isn't root anymore */
518 oldRootNode
.setParentSequenceNumber(newRootNode
.getSequenceNumber());
520 /* Close off the whole current latestBranch */
522 for (int i
= 0; i
< fLatestBranch
.size(); i
++) {
523 fLatestBranch
.get(i
).closeThisNode(splitTime
);
524 fTreeIO
.writeNode(fLatestBranch
.get(i
));
527 /* Link the new root to its first child (the previous root node) */
528 newRootNode
.linkNewChild(oldRootNode
);
530 /* Rebuild a new latestBranch */
531 int depth
= fLatestBranch
.size();
532 fLatestBranch
.clear();
533 fLatestBranch
.add(newRootNode
);
535 // Create new coreNode
536 for (int i
= 1; i
< depth
; i
++) {
537 CoreNode prevNode
= (CoreNode
) fLatestBranch
.get(i
- 1);
538 CoreNode newNode
= initNewCoreNode(prevNode
.getSequenceNumber(),
540 prevNode
.linkNewChild(newNode
);
541 fLatestBranch
.add(newNode
);
544 // Create the new leafNode
545 CoreNode prevNode
= (CoreNode
) fLatestBranch
.get(depth
- 1);
546 LeafNode newNode
= initNewLeafNode(prevNode
.getSequenceNumber(), splitTime
+ 1);
547 prevNode
.linkNewChild(newNode
);
548 fLatestBranch
.add(newNode
);
552 * Add a new empty core node to the tree.
554 * @param parentSeqNumber
555 * Sequence number of this node's parent
557 * Start time of the new node
558 * @return The newly created node
560 private @NonNull CoreNode
initNewCoreNode(int parentSeqNumber
, long startTime
) {
561 CoreNode newNode
= new CoreNode(fConfig
, fNodeCount
, parentSeqNumber
,
568 * Add a new empty leaf node to the tree.
570 * @param parentSeqNumber
571 * Sequence number of this node's parent
573 * Start time of the new node
574 * @return The newly created node
576 private @NonNull LeafNode
initNewLeafNode(int parentSeqNumber
, long startTime
) {
577 LeafNode newNode
= new LeafNode(fConfig
, fNodeCount
, parentSeqNumber
,
584 public HTNode
selectNextChild(CoreNode currentNode
, long t
) throws ClosedChannelException
{
585 assert (currentNode
.getNbChildren() > 0);
586 int potentialNextSeqNb
= currentNode
.getSequenceNumber();
588 for (int i
= 0; i
< currentNode
.getNbChildren(); i
++) {
589 if (t
>= currentNode
.getChildStart(i
)) {
590 potentialNextSeqNb
= currentNode
.getChild(i
);
597 * Once we exit this loop, we should have found a children to follow. If
598 * we didn't, there's a problem.
600 if (potentialNextSeqNb
== currentNode
.getSequenceNumber()) {
601 throw new IllegalStateException("No next child node found"); //$NON-NLS-1$
605 * Since this code path is quite performance-critical, avoid iterating
606 * through the whole latestBranch array if we know for sure the next
607 * node has to be on disk
609 if (currentNode
.isOnDisk()) {
610 return fTreeIO
.readNode(potentialNextSeqNb
);
612 return readNode(potentialNextSeqNb
);
616 public long getFileSize() {
617 return fConfig
.getStateFile().length();
620 // ------------------------------------------------------------------------
621 // Test/debugging methods
622 // ------------------------------------------------------------------------
624 /* Only used for debugging, shouldn't be externalized */
625 @SuppressWarnings("nls")
627 public String
toString() {
628 return "Information on the current tree:\n\n" + "Blocksize: "
629 + fConfig
.getBlockSize() + "\n" + "Max nb. of children per node: "
630 + fConfig
.getMaxChildren() + "\n" + "Number of nodes: " + fNodeCount
631 + "\n" + "Depth of the tree: " + fLatestBranch
.size() + "\n"
632 + "Size of the treefile: " + getFileSize() + "\n"
633 + "Root node has sequence number: "
634 + fLatestBranch
.get(0).getSequenceNumber() + "\n"
635 + "'Latest leaf' has sequence number: "
636 + fLatestBranch
.get(fLatestBranch
.size() - 1).getSequenceNumber();
640 * Start at currentNode and print the contents of all its children, in
641 * pre-order. Give the root node in parameter to visit the whole tree, and
642 * have a nice overview.
644 /* Only used for debugging, shouldn't be externalized */
645 @SuppressWarnings("nls")
646 private void preOrderPrint(PrintWriter writer
, boolean printIntervals
,
647 HTNode currentNode
, int curDepth
, long ts
) {
649 writer
.println(currentNode
.toString());
650 /* Print intervals only if timestamp is negative or within the range of the node */
651 if (printIntervals
&&
653 (ts
>= currentNode
.getNodeStart() && ts
<= currentNode
.getNodeEnd()))) {
654 currentNode
.debugPrintIntervals(writer
);
657 switch (currentNode
.getNodeType()) {
659 /* Stop if it's the leaf node */
664 final CoreNode node
= (CoreNode
) currentNode
;
665 /* Print the extensions, if any */
666 int extension
= node
.getExtensionSequenceNumber();
667 while (extension
!= -1) {
668 HTNode nextNode
= fTreeIO
.readNode(extension
);
669 preOrderPrint(writer
, printIntervals
, nextNode
, curDepth
, ts
);
672 /* Print the child nodes */
673 for (int i
= 0; i
< node
.getNbChildren(); i
++) {
674 HTNode nextNode
= fTreeIO
.readNode(node
.getChild(i
));
675 for (int j
= 0; j
< curDepth
; j
++) {
679 preOrderPrint(writer
, printIntervals
, nextNode
, curDepth
+ 1, ts
);
681 } catch (ClosedChannelException e
) {
682 Activator
.getDefault().logError(e
.getMessage());
692 public void debugPrintFullTree(PrintWriter writer
, boolean printIntervals
, long ts
) {
693 /* Only used for debugging, shouldn't be externalized */
695 preOrderPrint(writer
, false, fLatestBranch
.get(0), 0, ts
);
697 if (printIntervals
) {
698 preOrderPrint(writer
, true, fLatestBranch
.get(0), 0, ts
);
700 writer
.println('\n');