This is BTreeFile.rtf in view mode; [Download] [Up]
paperh22175 margl-907 margr0 margt0 margb0 {fonttblf0fswiss Helvetica;f1froman Times;f2fmodern Courier;f3ftech Symbol;f4froman Palantino;}fi0 ri0 ql sb0 f1 fs24 Release 2.0 Copyright f3 'e3f1 1990 by NeXT Computer, Inc. All Rights Reserved.
pard s2 li2620 fi0 ri1007 ql tx3124 tx3628 tx4132 f1 fs28 fs16
fs28
fs16
fs28 fs16 fs28
fs16
fs28 fs16 fs28
fs16
fs28 pard s19 li1108 fi0 ri1007 ql b fs36 fs16
fs36 BTreeFile
fs16
fs36 pard s20 li2116 fi0 ri1007 ql tx7156 b0 fs28 fs16 fs28 INHERITS FROM Object
fs16
fs28 s6 fs16 fs28 DECLARED IN BTreeFile.h
fs16
fs28 s22 fs16
fs28 CLASS DESCRIPTION
fs16
fs28 pard s2 li2620 fi0 ri1007 ql tx3124 tx3628 tx4132 fs16 fs28 Using the BTree class, the BTreeFile class implements one or more B* trees in a single Unix file. The implementation of the B* tree has been separated from the implementation of its backing store to allow for alternative backing store implementations. The BTreeFile class is an example of an alternative backing store implementation.
fs16
fs28 fs16 fs28 Every BTreeFile maintains a single default B* tree; the b openBTreeb0 method opens the default B* tree. The BTreeFile class can also manage additional, named B* trees. The maximum number of B* trees supported by a file is determined by the virtual memory page size in effect when the file was created. The BTreeFile class reports errors with the NX_RAISE().
fs16
fs28 pard s22 li2116 fi0 ri1007 ql tx7156 fs16
fs28 INSTANCE VARIABLES
fs16
fs28 pard s23 li7156 fi-4536 ri1007 ql tx7156 tx10180 tx10684 fs16 fs28 i Inherited from Objecti0 Class isa;
fs16
fs28 i Declared in BTreeFilei0 char *fileName;
pard s12 li7660 fi-503 ri1007 ql tx10180 tx10684 NXHashTable *btreesByName;
id defaultBTree;
pard s23 li7156 fi-4536 ri1007 ql tx7156 tx10180 tx10684 fs16
fs28 fileName The name of the file on disk
fs16
fs28 btreesByName A hash table containing the names of all the named B* trees in the file
fs16
fs28 defaultBTree The BTree object managing the default B* tree
pard s22 li2116 fi0 ri1007 ql tx7156 fs16
fs28 METHOD TYPES
fs16
fs28 pard s23 li7156 fi-4536 ri1007 ql tx7156 tx10180 tx10684 fs16 fs28 Creating and freeing instances f3 - f1 free
pard s12 li7660 fi-503 ri1007 ql tx10180 tx10684 + new
+ newFile:
+ newFile:isInstant:canUndo:
+ openFile:forWriting:
pard s23 li7156 fi-4536 ri1007 ql tx7156 tx10180 tx10684 fs16
fs28 Managing B* trees f3 - f1 contents
pard s12 li7660 fi-503 ri1007 ql tx10180 tx10684 f3 - f1 createBTreeNamed:
f3 - f1 openBTree
f3 - f1 openBTreeNamed:
f3 - f1 removeBTreeNamed:
pard s23 li7156 fi-4536 ri1007 ql tx7156 tx10180 tx10684 fs16
fs28 Saving and undoing changes f3 - f1 canUndo
pard s12 li7660 fi-503 ri1007 ql tx10180 tx10684 f3 - f1 save
f3 - f1 undo
pard s23 li7156 fi-4536 ri1007 ql tx7156 tx10180 tx10684 fs16
fs28 Handling unexpected process termination
fi0 + recoverFile:
fi-4536 fs16
fs28 Restarting f3 - f1 discardPriorTo:
pard s12 li7660 fi-503 ri1007 ql tx10180 tx10684 f3 - f1 isRestartable
f3 - f1 restartFrom:
pard s23 li7156 fi-4536 ri1007 ql tx7156 tx10180 tx10684 fs16
fs28 Miscellaneous + compressFile:
pard s12 li7660 fi-503 ri1007 ql tx10180 tx10684 f3 - f1 fileName
pard s22 li2116 fi0 ri1007 ql tx7156 fs16
fs28 CLASS METHODS
fs16
fs28 s10 b fs28 fs16
fs28 compressFile:
pard s4 li3628 fi-1007 ri1007 ql b0 fs28 + (void)b compressFile:b0 (const char *)i fileName
fs16
fs28 pard s2 li2620 fi0 ri1007 ql tx3124 tx3628 tx4132 i0 fs16 fs28 Removes all unused space from i fileNamei0 . This method should not be used with files which are frequently modified, since it will reduce update performance. The space savings provided by this method may exceed 35 per cent. This method may take a long time to run.
fs16
fs28 pard s10 li2116 fi0 ri1007 ql tx7156 b fs28 fs16
fs28 new
pard s4 li3628 fi-1007 ri1007 ql b0 fs28 + b new
fs16
fs28 pard s2 li2620 fi0 ri1007 ql tx3124 tx3628 tx4132 b0 fs16 fs28 Creates a B* tree backing store in a temporary file named by b mktemp(3)b0 , and returns a BTreeFile object. If the file cannot be created, this method raises an exception. In the event of unexpected process termination, the temporary file will be destroyed by the boot process. The temporary file is NOT removed when the BTreeFile object is freed.
fs16
fs28 pard s10 li2116 fi0 ri1007 ql tx7156 b fs28 fs16
fs28 newFile:
pard s4 li3628 fi-1007 ri1007 ql b0 fs28 + b newFile:b0 (const char *)i fileName
fs16
fs28 pard s2 li2620 fi0 ri1007 ql tx3124 tx3628 tx4132 i0 fs16 fs28 Creates a B* tree backing store in i fileNamei0 , and returns a BTreeFile object. If i fileNamei0 already exists, or if it cannot be created, this method raises an exception. If the process is terminated unexpectedly while the file is open for writing, the file may be left in an unrecoverable state.
fs16
fs28 pard s10 li2116 fi0 ri1007 ql tx7156 b fs28 fs16
fs28 newFile:isInstant:canUndo:
pard s4 li3628 fi-1007 ri1007 ql b0 fs28 + b newFile:b0 (const char *)i fileName
fi0 b i0 isInstant:b0 (BOOL)i instantFlag
fi0 b i0 canUndo:b0 (BOOL)i undoFlag
fs16
fs28 pard s2 li2620 fi0 ri1007 ql tx3124 tx3628 tx4132 i0 fs16 fs28 Creates a recoverable B* tree backing store in i fileNamei0 . Files created by this method are guaranteed to be recoverable if the process is terminated unexpectedly. This guarantee is achieved at a modest performance cost.
fs16
fs28 fs16 fs28 If i instantFlagi0 is true, the file is guaranteed to be instantly recoverable; an explicit recovery operation will not be required before the file may be successfully opened for writing following unexpected process termination. The guarantee of instant recovery incurs a more substantial performance cost, but avoids the possibility of a lengthy recovery following unexpected process termination.
fs16
fs28 fs16 fs28 If i undoFlagi0 is true, the file will support basic transaction management through the b saveb0 and b undob0 methods. In combination with instant recovery, this provides instant roll forward and backward capability through the b restartFrom:b0 method.
fs16
fs28 fs16 fs28 If the file is created successfully, this method attempts to retain exclusive access to the file with b flock(2)b0 .
fs16
fs28 pard s10 li2116 fi0 ri1007 ql tx7156 b fs28 fs16
fs28 openFile:forWriting:
pard s4 li3628 fi-1007 ri1007 ql b0 fs28 + b openFile:b0 (const char *)i fileName b i0 forWriting:b0 (BOOL)i writingFlag
fs16
fs28 pard s2 li2620 fi0 ri1007 ql tx3124 tx3628 tx4132 i0 fs16 fs28 Opens i fileNamei0 , and returns a BTreeFile object. If i writingFlagi0 is true, i fileNamei0 is opened for reading and writing, and the method attempts to secure exclusive access to i fileNamei0 with b flock(2)b0 . Otherwise, i fileNamei0 is opened for reading only, and the method attempts to secure shared access to i fileNamei0 with b flock(2)b0 .
fs16
fs28 fs16 fs28 If i fileNamei0 does not exist, or if it cannot be accessed, or if it does not contain a B* tree backing store, this method raises an exception. This method will also raise an exception if i writingFlagi0 is true, and i fileNamei0 is internally inconsistent and not instantly recoverable, or if i writingFlagi0 is true, and i fileNamei0 is internally inconsistent and not recoverable. If i fileNamei0 is recoverable, the b recover:b0 method may be used to recover its contents.
fs16
fs28 pard s10 li2116 fi0 ri1007 ql tx7156 b fs28 fs16
fs28 recoverFile:
pard s4 li3628 fi-1007 ri1007 ql b0 fs28 + (void)b recoverFile:b0 (const char *)i fileName
fs16
fs28 pard s2 li2620 fi0 ri1007 ql tx3124 tx3628 tx4132 i0 fs16 fs28 Recovers the contents of i fileNamei0 . This method raises an exception if i fileNamei0 does not exist, or if it cannot be accessed, or if it does not contain a B* tree backing store, or if it is internally inconsistent and not recoverable. This method attempts to secure exclusive access to i fileNamei0 with b flock(2)b0 .
fs16
fs28 pard s22 li2116 fi0 ri1007 ql tx7156 fs16
fs28 INSTANCE METHODS
fs16
fs28 s10 b fs28 fs16
fs28 canUndo
pard s4 li3628 fi-1007 ri1007 ql b0 fs28 f3 - f1 (BOOL)b canUndo
fs16
fs28 pard s2 li2620 fi0 ri1007 ql tx3124 tx3628 tx4132 b0 fs16 fs28 Returns boolean true if the file supports transaction management. A file supports transaction management if it was created with the b new:isInstant:canUndo:b0 method, with the i canUndoi0 argument true.
fs16
fs28 fs16 fs28 See also: f3 - b f1 saveb0 , f3 - b f1 undo
fs16
fs28 pard s10 li2116 fi0 ri1007 ql tx7156 fs28 fs16
fs28 contents
pard s4 li3628 fi-1007 ri1007 ql b0 fs28 f3 - f1 (char **)b contents
fs16
fs28 pard s2 li2620 fi0 ri1007 ql tx3124 tx3628 tx4132 b0 fs16 fs28 Returns a nullf3 - f1 terminated array of pointers to strings containing the names of all of the named B* trees in the file. The caller is responsible for freeing the array and its contents with b free(3)b0 .
fs16
fs28 pard s10 li2116 fi0 ri1007 ql tx7156 b fs28 fs16
fs28 createBTreeNamed:
pard s4 li3628 fi-1007 ri1007 ql b0 fs28 f3 - f1 (BTree *)b createBTreeNamed:b0 (const char *)i btreeName
fs16
fs28 pard s2 li2620 fi0 ri1007 ql tx3124 tx3628 tx4132 i0 fs16 fs28 Creates and returns a BTree object for a B* tree named i btreeNamei0 . This method raises an exception if there is already a B* tree named i btreeNamei0 in the file. To dispose of the BTree object and close the B* tree, use BTree's b freeb0 method.
fs16
fs28 pard s10 li2116 fi0 ri1007 ql tx7156 b fs28 fs16
fs28 discardPriorTo:
pard s4 li3628 fi-1007 ri1007 ql b0 fs28 f3 - f1 (void)b discardPriorTo:b0 (struct timeval)i threshhold
fs16
fs28 pard s2 li2620 fi0 ri1007 ql tx3124 tx3628 tx4132 i0 fs16 fs28 If the BTreeFile is restartable, this method discards file history older than i threshholdi0 . This involves a single pass over the entire file, and may be very time consuming for large files. i threshholdi0 is given as a i struct timevali0 describing a Greenwich mean time, as returned by b gettimeofday(2)b0 . If the BTreeFile is not restartable, this method raises an exception.
fs16
fs28 fs16 fs28 See also: f3 - b f1 restartFrom:b0 , f3 - b f1 isRestartable
fs16
fs28 pard s10 li2116 fi0 ri1007 ql tx7156 fs28 fs16
fs28 fileName
pard s4 li3628 fi-1007 ri1007 ql b0 fs28 f3 - f1 (const char *)b fileName
fs16
fs28 pard s2 li2620 fi0 ri1007 ql tx3124 tx3628 tx4132 b0 fs16 fs28 Returns the name of the file associated with the BTreeFile object.
fs16
fs28 pard s10 li2116 fi0 ri1007 ql tx7156 b fs28 fs16
fs28 free
pard s4 li3628 fi-1007 ri1007 ql b0 fs28 f3 - b f1 free
fs16
fs28 pard s2 li2620 fi0 ri1007 ql tx3124 tx3628 tx4132 b0 fs16 fs28 Saves changes, closes the file, and frees the BTreeFile object.
fs16
fs28 pard s10 li2116 fi0 ri1007 ql tx7156 b fs28 fs16
fs28 isRestartable
pard s4 li3628 fi-1007 ri1007 ql b0 fs28 f3 - f1 (BOOL)b isRestartable
fs16
fs28 pard s2 li2620 fi0 ri1007 ql tx3124 tx3628 tx4132 b0 fs16 fs28 Returns boolean true if the BTreeFile is restartable. A file is restartable if it was created with the b new:isInstant:canUndo:b0 method, with both boolean arguments true.
fs16
fs28 fs16 fs28 See also: f3 - b f1 discardPriorTo:b0 , f3 - b f1 restartFrom:
fs16
fs28 pard s10 li2116 fi0 ri1007 ql tx7156 fs28 fs16
fs28 openBTree
pard s4 li3628 fi-1007 ri1007 ql b0 fs28 f3 - f1 (BTree *)b openBTree
fs16
fs28 pard s2 li2620 fi0 ri1007 ql tx3124 tx3628 tx4132 b0 fs16 fs28 Returns a BTree object for the default B* tree. This method returns the same BTree object every time it is called. To dispose of the BTree object and close the B* tree, use BTree's b freeb0 method.
fs16
fs28 pard s10 li2116 fi0 ri1007 ql tx7156 b fs28 fs16
fs28 openBTreeNamed:
pard s4 li3628 fi-1007 ri1007 ql b0 fs28 f3 - f1 (BTree *)b openBTreeNamed:b0 (const char *)i btreeName
fs16
fs28 pard s2 li2620 fi0 ri1007 ql tx3124 tx3628 tx4132 i0 fs16 fs28 Opens and returns a BTree object for the B* tree named i btreeNamei0 . This method raises an exception if the file does not contain a B* tree named i btreeNamei0 . This method returns the same BTree object every time it is called with the same name. To dispose of the BTree object and close the B* tree, use BTree's b freeb0 method.
fs16
fs28 pard s10 li2116 fi0 ri1007 ql tx7156 b fs28 fs16
fs28 removeBTreeNamed:
pard s4 li3628 fi-1007 ri1007 ql b0 fs28 f3 - f1 (void)b removeBTreeNamed:b0 (const char *)i btreeName
fs16
fs28 pard s2 li2620 fi0 ri1007 ql tx3124 tx3628 tx4132 i0 fs16 fs28 Removes the B* tree named i btreeNamei0 from the file. This method raises an exception if the B* tree named i btreeNamei0 is in use, or if the file does not contain a B* tree named i btreeNamei0 .
fs16
fs28 pard s10 li2116 fi0 ri1007 ql tx7156 b fs28 fs16
fs28 restartFrom:
pard s4 li3628 fi-1007 ri1007 ql b0 fs28 f3 - f1 (void)b restartFrom:b0 (struct timeval)i startTime
fs16
fs28 pard s2 li2620 fi0 ri1007 ql tx3124 tx3628 tx4132 i0 fs16 fs28 If the BTreeFile is restartable, this method restarts it instantly from i startTimei0 . i startTimei0 is given as a i struct timevali0 describing a Greenwich mean time, as returned by b gettimeofday(2)b0 . This method does not permanently alter the file, and is much faster than permanently discarding file history with b discardPriorTo:b0 . If the BTreeFile is not restartable, this method raises an exception.
fs16
fs28 fs16 fs28 See also: f3 - b f1 isRestartable
fs16
fs28 pard s10 li2116 fi0 ri1007 ql tx7156 fs28 fs16
fs28 save
pard s4 li3628 fi-1007 ri1007 ql b0 fs28 f3 - f1 (void)b save
fs16
fs28 pard s2 li2620 fi0 ri1007 ql tx3124 tx3628 tx4132 b0 fs16 fs28 Saves changes to disk. On return from this method, the file is guaranteed to be internally consistent. If the file supports transaction management, this method commits the outstanding transaction, and begins a new one.
fs16
fs28 fs16 fs28 See also: f3 - b f1 canUndob0 , b undo
fs16
fs28 pard s10 li2116 fi0 ri1007 ql tx7156 fs28 fs16
fs28 undo
pard s4 li3628 fi-1007 ri1007 ql b0 fs28 f3 - f1 (void)b undo
fs16
fs28 pard s2 li2620 fi0 ri1007 ql tx3124 tx3628 tx4132 b0 fs16 fs28 If the file supports transaction management, this method aborts any outstanding transaction, and returns the file to the state created by the last b saveb0 message, or to the state in which it was opened or created, if b saveb0 has not been performed. If the file does not support transaction management, this method raises an exception.
fs16
fs28 fs16 fs28 See also: f3 - b f1 canUndob0 , b save
fs16
fs28 }These are the contents of the former NiCE NeXT User Group NeXTSTEP/OpenStep software archive, currently hosted by Netfuture.ch.