This is NSByteStore.rtf in view mode; [Download] [Up]
paperh18648 margl-907 margr0 margt0 margb0 fi0 ri0 ql sb0 f1 fs24 Copyright f3 'e3f1 1994 by NeXT Computer, Inc. All Rights Reserved.
s4 li100 fi0 ri1007 ql f0 b fs36 fs100
fs36 NSByteStore
pard s11 li2872 fi-2771 ri1007 ql tx2872 f1 b0 fs28 fs48
fs28 f0 b fs24 Inherits From:tab b0 fs28 f1 NSObject
fs20
fs28 s6 f0 b fs24 Conforms To:tab b0 fs28 f1 NSObject (NSObject)
fs20
fs28 s7 f0 b fs24 Declared In:tab b0 fs28 f1 Foundation/NSByteStore.h
fs20
fs28 pard s16 li100 fi0 ri1007 ql f0 b fs28 fs20
fs28 Class Description
fs14
fs28 pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs2
fs28 An NSByteStore object manages a single memory-based heap. Use NSByteStore to allocate storage in data-intensive applications. Its main feature is transaction management, which makes compound operations atomic and ensures data integrity.
fs16
fs28 You address the blocks of storage that an NSByteStore manages through unsigned integers called block numbers. To gain access to the contents of a block, you first must open the block for reading or writing. When you open a block, the NSByteStore resolves the block number into a pointer. While a block is open, you can address its contents using the pointer and can safely assume that the block won'27t move. Once you close the block, however, the NSByteStore is free to move it in order to compact storage; so the pointer may become invalid.
fs16
fs28 The contents of an NSByteStore are relocatable to and from other instances of NSByteStore and its subclasses. Although the address of a block becomes invalid when the block is relocated, its block number remains constant. Since block numbers are indirect references to data, it'27s possible to retrieve the contents of an NSByteStore without invalidating block number-based referential data structures residing in the NSByteStore, like linked lists or trees. This makes it easy to copy complex structures or to quickly save them to a file.
fs16
fs28 A subclass of NSByteStore, NSByteStoreFile, stores data in a file so that you can retain data created and changed by your application. For more information, see its class description.
fs16
fs28 pard s15 li477 fi0 ri1007 ql f0 b fs24 fs4
fs24 Transactions
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs28 fs16
fs28 NSByteStore implements i transactionsi0 , allowing several operations to be grouped together in such a way that either all of them take effect, or none of them do. Transactions help to ensure semantic integrity by making compound operations atomic, and they provide a convenient way to undo a series of changes. If you use NSByteStoreFile, the use of transactions also ensures data integrity against process and system crashes. This means that if a system loses power, the NSByteStoreFile'27s contents can be recovered intact on power up, in the state they were in after the last transaction that actually finished.
fs16
fs28 Transactions are either enabled or disabled for an object. Most likely, you will want to disable transactions for NSByteStores (unless you want the undo capability) and enable them for NSByteStoreFiles. When transactions are enabled, NSByteStore copies blocks that your application opens for writing. Thus, updates are slower when transactions are enabled. If you are using NSByteStore directly, its contents are always destroyed by a system crash, so the only advantage to using transactions is the undo capability. If you are using NSByteStoreFile, enabling transactions may save some of the changes made before a system crash. Therefore, you should always use transactions with NSByteStoreFile except if it contains data that can be easily reconstructed, such as an index.
fs16
fs28 pard s15 li477 fi0 ri1007 ql f0 b fs24 fs4
fs24 Using Transactions
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs28 fs16
fs28 A single transaction begins with a b startTransactionb0 message and ends with either a b commitTransactionb0 or b abortTransactionb0 message. b startTransactionb0 enables transactions if they are disabled. Sending b commitTransactionb0 means you want the changes made by this transaction to take effect. b abortTransactionb0 means you want to cancel the changes made by this transaction.
fs16
fs28 You can check whether transactions have been enabled with b areTransactionsEnabledb0 . You may want to do this if your code is invoked by higher level methods that determine the transaction management policy for the application. For example, NSByteStore uses b areTransactionsEnabledb0 to determine whether or not to invoke b startTransactionb0 before responding to an b emptyb0 message.
fs16
fs28 You can nest transactions. The first b startTransactionb0 message (or the first message that opens a block after b enableTransactionsb0 ) starts transaction 1. If you send b startTransactionb0 again before ending transaction 1, it begins transaction 2, which is nested inside transaction 1. The b nestingLevelb0 method returns the current nesting level of transactions. b startTransactionb0 also returns the nesting level as the transaction'27s ID.
fs16
fs28 The trick with nesting transactions is: i the changes a transaction makes aren'27t really made until the nesting level returns to 0i0 . In other words, changes don'27t actually take effect until the top-level transaction is committed. This means that any blocks that any of the transactions have opened for writing will not be available until the all of the transactions are finished. So, if you start a transaction at nesting level 2, make some changes to blocks 3, 5, and 7, and then you send b commitTransactionb0 , all that b commitTransactionb0 really does is set the nesting level to 1 and tell transaction 1 about the changes to blocks 3, 5, and 7. If you then send b commitTransactionb0 at transaction 1, b commitTransactionb0 sets the nesting level to 0. Because the nesting level is now 0, the changes can take place. Blocks 3, 5, and 7 are overwritten with the changes made during transaction 2 and are made available. If instead you decide to abort transaction 1 (by sending b abortTransactionb0 ), the changes transaction 2 made to blocks 3, 5, and 7 are cancelled, as well as any changes transaction 1 made to any blocks. In this way, the parent of a transaction can undo changes made by their children, but the children cannot undo the changes made by their parents.
fs16
fs28 Note that if your code makes changes outside any transaction while transactions are enabled, an enclosing transaction is started automatically. The next invocation of b startTransactionb0 , if any, before an intervening abort or commit, simply picks up this enclosing transaction and reports a nesting level of 1. Thus, if nesting isn'27t needed, your code can simply enable transactions initially with a pair of b startTransactionb0 /b commitTransactionb0 messages, and thereafter use only b commitTransactionb0 to mark transaction boundaries. New transactions implicitly begin with the first modification following each commit.
fs16
fs28 Any modifications that haven'27t been committed are aborted when an NSByteStore is freed.
fs16
fs28 pard s15 li477 fi0 ri1007 ql f0 b fs24 fs4
fs24 Opening Blocks for Reading or Writing
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs28 fs16
fs28 When you open a block for reading or writing, that block is unavailable until you specify that you are finished.
fs16
fs28 When you are finished reading a block, you send b closeBlock:b0 . Any method that accesses information about a block opens it for reading. This means not only does b readBlock:range:b0 open a block for reading, but so does b sizeOfBlock:b0 , which returns the block'27s size. The b copyBlock:b0 method opens the block for reading, but it also closes it when finished (unless you already had that block opened for reading). Even if you commit a transaction before you send b closeBlock:b0 , the block remains open for reading.
fs16
fs28 Any method that changes a block'27s contents opens the block for writing. This means not only does b openBlock:range:b0 open a block for writing, but so do the methods b copyBytes:toBlock:range:b0 , b createBlockOfSize:b0 , and b freeBlock:b0 . You indicate that you are finished with a block you have open for writing by having its changes take effect. Closing the block with b closeBlock:b0 does i noti0 make your changes take effect, i even if transactions are disabledi0 . Regardless of whether transactions are enabled or disabled, you must send b commitTransactionb0 to have your changes actually be made.
fs16
fs28 If transactions are disabled, b commitTransactionb0 commits all the changes made to blocks since that last b commitTransactionb0 or b abortTransactionb0 message was sent. b abortTransactionb0 cancels all the changes made since the last b commitTransactionb0 .
fs16
fs28 pard s16 li100 fi0 ri1007 ql f0 b fs24
fs28 Creating an NSByteStore
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 + (NSByteStore *)b byteStoreb0 tab Returns a new NSByteStore with transactions disabled.
pard s16 li100 fi0 ri1007 ql f0 b fs48
fs28 Managing the NSByteStore
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (unsigned)b countb0 tab Returns the number of blocks in the NSByteStore at transaction level 0. That is, if you have created or freed some blocks but those changes have not been committed at transaction level 0, b countb0 will not reflect those changes.
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b emptyb0 tab Frees all blocks of memory in the NSByteStore. If transactions are enabled, this method starts and commits a new transaction.
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b getBlocks:b0 (unsigned *)i blocksi0 tab Returns in i blocksi0 a C-style array of block numbers at transaction level 0. The caller must free the returned array.
fi-6552 fs16
fs28 fi-6552 {f3 -} (unsigned)b rootBlockb0 tab Returns the number of the root block, which by convention is used as a table of contents or a directory.
pard s16 li100 fi0 ri1007 ql f0 b fs48
fs28 Creating, Copying, and Freeing Blocks
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (unsigned)b createBlockOfSize:b0 (unsigned)i sizei0 tab Returns a block number for a new block of i sizei0 bytes with the contents initialized to zero. Creating a block with size 0 is allowed.
fi-6552 fs16
fs28 fi-6552 {f3 -} (unsigned)b copyBlock:b0 (unsigned)i aBlocki0 tab Returns a block number for a new block whose size and
s9 li7030 fi-6553 fi-5796 b range:b0 (NSRange)i rangei0 tab tab contents are identical to the memory region in block i aBlocki0 specified by i rangei0 .
s8 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b freeBlock:b0 (unsigned)i aBlocki0 tab Removes and frees the block i aBlocki0 .
pard s16 li100 fi0 ri1007 ql f0 b fs48
fs28 Opening and Closing Blocks
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (void *)b openBlock:b0 (unsigned)i aBlocki0 tab Opens for writing the memory region in block i aBlocki0
s9 li7030 fi-6553 fi-5796 b range:b0 (NSRange)i rangei0 tab tab specified by i rangei0 . A pointer to the region is returned.
s8 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (const void *)b readBlock:b0 (unsigned)i aBlockb i0 tab b0 Opens for reading the memory region in block i aBlock.i0
s9 li7030 fi-6553 fi-5796 b range:b0 (NSRange)i rangei0 tab tab specified by i rangei0 . A pointer to the region is returned.
s8 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b closeBlock:b0 (unsigned)i aBlocki0 tab Closes the block i aBlocki0 .
pard s16 li100 fi0 ri1007 ql f0 b fs48
fs28 Managing Block Sizes
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (void)b resizeBlock:b0 (unsigned)i aBlocki0 tab Resizes the block i aBlocki0 to i sizei0 bytes. This
s9 li7030 fi-6553 fi-5796 b toSize:b0 (unsigned)i sizei0 tab tab method may change the location of the block as well.
s8 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (unsigned)b sizeOfBlock:b0 (unsigned)i aBlocki0 tab Returns the size in bytes of the block i aBlocki0 .
pard s16 li100 fi0 ri1007 ql f0 b fs48
fs28 Using Transactions
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (unsigned)b startTransactionb0 tab Begins a new transaction, enabling transactions if necessary, for the current context. This transaction will be aborted or committed before all other outstanding transactions. Returns a number that both identifies the new transaction and indicates the number of transactions outstanding.
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b abortTransactionb0 tab Reverts the NSByteStore to the state it was in before the last b startTransactionb0 message or the last b commitTransactionb0 message. Any blocks that had been opened are made available to other store contexts.
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b commitTransactionb0 tab Commits all changes made to blocks opened since the last b startTransactionb0 or the last b commitTransactionb0 and closes those blocks. If transactions are disabled or the nesting level becomes 0, this method makes all of the changed blocks available to other contexts.
fi-6552 fs16
fs28 fi-6552 {f3 -} (BOOL)b areTransactionsEnabledb0 tab Returns YES if transactions are enabled for the NSByteStore, NO if not. Transactions are enabled by the method b startTransactionb0 .
fi-6552 fs16
fs28 fi-6552 {f3 -} (unsigned)b nestingLevelb0 tab Returns the number of transactions pending against the NSByteStore.
fi-6552 fs16
fs28 fi-6552 {f3 -} (unsigned)b changeCountb0 tab Returns the number of changes made to the NSByteStore'27s contents since it was initialized. This number equals the number of b commitTransactionb0 and b abortTransactionb0 messages the NSByteStore has received.
pard s16 li100 fi0 ri1007 ql f0 b fs48
fs28 Changing the Contents
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (void)b copyBytes:b0 (const void *)i newDatai0 tab Copies the series of bytes pointed to by i newDatai0 into the
s9 li7030 fi-6553 fi-5796 b toBlock:b0 (unsigned)i aBlocki0 tab tab memory region in block i aBlocki0 specified by i rangei0 . This
b range:b0 (NSRange)i rangei0 tab tab method will expand the block'27s size if the data will not fit in the location specified by i rangei0 .
s8 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (NSData *)b contentsAsDatab0 tab Creates a virtual memory image of the NSByteStore.
fi-6552 fs16
fs28 fi-6552 {f3 -} (void)b replaceContentsWithData:b0 (NSData *)i datai0 tab Replaces the contents of the NSByteStore with virtual memory image i datai0 . This method ignores and erases any pending writes to the NSByteStore.
}These are the contents of the former NiCE NeXT User Group NeXTSTEP/OpenStep software archive, currently hosted by Netfuture.ch.