home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.2 (Developer) / NS_dev_3.2.iso / NextDeveloper / Headers / store / IXStore.h next >
Text File  |  1993-07-17  |  9KB  |  207 lines
  1. /*
  2. IXStore.h
  3. Copyright 1991, NeXT Computer, Inc.
  4. */
  5.  
  6. #import    "protocols.h"
  7. #import <mach/mach.h>
  8. #import    <objc/hashtable.h>
  9. #import    <objc/Object.h>
  10.  
  11. @class    NXData;
  12.  
  13. // This pasteboard type is used to copy store images created by 
  14. // getContents:andLength: between processes via the pasteboard server.
  15.  
  16. extern NXAtom    IXStorePboardType;
  17.  
  18. @interface IXStore: Object
  19. {
  20. @public
  21.     unsigned            changeCount;
  22. @private
  23.     unsigned            nestingLevel;
  24.     struct StoreBlockServer    *blockServer;
  25.     struct StoreBroker        *storeBroker;
  26.     struct StoreTransRecord    *queueForward;
  27.     struct StoreTransRecord    *queueReverse;
  28.     struct             {
  29.     unsigned        exceptions:1;
  30.     unsigned        freeOnWrite:1;
  31.     unsigned        RESERVED1:30;
  32.     }                _storeStatus;
  33. }
  34.  
  35. // These two methods set and report the interface error reporting policy.  For 
  36. // compatibility with 3.0 FCS, most of the methods implemented by this class 
  37. // raise an exception when passed an invalid argument, such as an invalid block 
  38. // handle.  This can be quite cumbersome to use.  When exceptions are disabled, 
  39. // the method return values indicate success or failure.
  40.  
  41. - enableExceptions:(BOOL)aBoolean;
  42. - (BOOL)areExceptionsEnabled;
  43.  
  44. // Copying a store creates an independent concurrent context.  The number of 
  45. // contexts is limited only by resource consumption.  Changes made by one 
  46. // context do not affect another context until they are committed.
  47.  
  48. - copy;
  49.  
  50. // The underlying objects shared by all contexts are reference counted.  When 
  51. // the last context is freed, the underlying objects are also freed.  Freeing 
  52. // the underlying objects destroys the contents of the store.
  53.  
  54. - free;
  55.  
  56. - init; // Creates a memory based store.
  57.  
  58. // These two methods are used when archiving stores.  If freeOnWrite is sent, 
  59. // the receiver will free itsself after archiving.  willFreeOnWrite returns 
  60. // true if the receiver will free itsself after archiving.
  61.  
  62. - freeOnWrite;
  63. - (BOOL)willFreeOnWrite;
  64.  
  65. // The effects of methods that create and free blocks are delayed until 
  66. // transaction commit, even if transactions are not enabled.
  67.  
  68. // Opening or resizing a block locks it against access by other contexts.  
  69. // Closing a block unlocks it, unless transactions are enabled and the block 
  70. // has been modified; in that case, the close is deferred until transaction 
  71. // commit.  Blocks are closed automatically when the opening transaction ends.
  72.  
  73. // Attempting to open or resize a locked block will result in an IX_LockedError 
  74. // exception.  This permits the implementation of a two phase locking strategy.  
  75.  
  76. // Creates a new block of the requested size.  A block size of zero is valid.
  77. // The contents of the block are initialized to zero.  Returns the block handle
  78. // by reference.
  79.  
  80. - createBlock:(unsigned *)handle ofSize:(unsigned)size;
  81.  
  82. // Frees an existing block.  Once freed, the block may not be operated upon 
  83. // except by closeBlock: or abortBlock:, unless the transaction is aborted.  
  84. // Returns self, or nil if the supplied handle is invalid.
  85.  
  86. - freeBlock:(unsigned)handle;
  87.  
  88. - (BOOL)blockExists:(unsigned)blockHandle; // tests existence of the block
  89. - abortBlock:(unsigned)handle; // aborts all changes to the block
  90. - closeBlock:(unsigned)handle; // commits all changes and closes the block
  91.  
  92. // Copies the designated block, returning the handle of the copy, or zero if 
  93. // the supplied handle is not valid.
  94.  
  95. - (unsigned)copyBlock:(unsigned)handle 
  96.     atOffset:(unsigned)offset forLength:(unsigned)length;
  97.  
  98. // These two methods return a pointer to the contents of the designated block, 
  99. // or NULL if the supplied handle is invalid.  openBlock:atOffset:forLength: 
  100. // copies the block first, if transactions are enabled, and returns a pointer 
  101. // to the copy.  readBlock:atOffset:forLength: does not copy the block.
  102.  
  103. - (void *)openBlock:(unsigned)handle
  104.     atOffset:(unsigned)offset forLength:(unsigned)length;
  105. - (void *)readBlock:(unsigned)handle
  106.     atOffset:(unsigned)offset forLength:(unsigned)length;
  107.  
  108. // This method copies data into a block in the store in the most efficient 
  109. // manner possible.  Data should never by copied into a block with vm_copy, 
  110. // unless the store is known to be a member of the class IXStore, since the
  111. // subclasses of IXStore may use file paging that does not support vm_copy.
  112. - copyData:(void *)data toBlock:(unsigned)handle
  113.     atOffset:(unsigned)offset forLength:(unsigned)length;
  114.  
  115. // These two methods are designed to permit a store to be used over the wire. 
  116. // exportBlock:atOffset:forLength: returns an NXData containing the contents 
  117. // of the block.  importBlock:atOffset:forLength: takes an NXData containing 
  118. // the new contents of the block, and opens the block for writing, then copies 
  119. // from the NXData to the contents of the block.
  120.  
  121. - (NXData *)exportBlock:(unsigned)handle 
  122.     atOffset:(unsigned)offset forLength:(unsigned)length;
  123. - importBlock:(unsigned)handle 
  124.     atOffset:(unsigned)offset fromData:(NXData *)data;
  125.  
  126. // These two methods report and modify the size of a block, respectively.  A 
  127. // size of zero is valid; there are no contents associated with a block of zero 
  128. // size.  Resizing a block locks the block, and may cause the block's in memory 
  129. // location to change.  If the block must be accessed after resizing, it should 
  130. // be reopened to obtain a pointer to the new in memory location.  The contents 
  131. // of the newly created portion of a block that grows are zeroed.
  132.  
  133. - (unsigned)sizeOfBlock:(unsigned)handle;
  134. - resizeBlock:(unsigned)handle toSize:(unsigned)size;
  135.  
  136. // By default, transactions are disabled.  Starting the first transaction 
  137. // permanently enables them.  There is a performance penalty for enabling 
  138. // transactions, since blocks must be copied before they can be modified when 
  139. // transactions are enabled.  With transactions disabled, aborting a block or 
  140. // transaction is equivalent to committing the block or transaction.
  141.  
  142. // When transactions are enabled, calls to startTransaction are optional, 
  143. // since a new transaction is automatically started by the first operation that 
  144. // modifies the contents of the store.  Calling startTransaction more than once 
  145. // before a call to commitTransaction or abortTransaction causes nesting.  The 
  146. // nesting level is returned by startTransaction.  Within a nested transaction, 
  147. // the effects of createBlock:ofSize: and freeBlock: are reversible relative to 
  148. // the enclosing transaction, as are all changes made to blocks opened by the 
  149. // nested transaction.  When a nested transaction is committed, its results are 
  150. // carried into the enclosing transaction as modifications.
  151.  
  152. - (unsigned)startTransaction;
  153. - abortTransaction;
  154. - commitTransaction;
  155.  
  156. - (unsigned)nestingLevel; // returns the transaction nesting level
  157. - (BOOL)areTransactionsEnabled; // true if transactions are already enabled
  158. - (int)changeCount; // increases by one for each commit or abort transaction
  159.  
  160. // Returns the number of blocks in the store, taking into account changes 
  161. // pending in the receiving context.
  162.  
  163. - (unsigned)count;
  164.  
  165. // Returns the largest valid block handle; this provides an upper bound on 
  166. // valid block handles, useful for iterating over all blocks in the store.
  167.  
  168. - (unsigned)capacity;
  169.  
  170. // Frees all blocks in the store.  This method starts and commits a private 
  171. // transaction, if transactions are enabled.  The private transaction will be 
  172. // nested within any outstanding transactions.
  173.  
  174. - empty;
  175.  
  176. // These methods remove free space by relocating blocks toward the origin of 
  177. // the virtual address space defined by the store.  A timeout of zero allows 
  178. // the compaction to run to completion.
  179.  
  180. - compact;
  181. - compactWithTimeout:(int)msecs;
  182.  
  183. // The resident size limit restricts the amount of backing store that may 
  184. // remain mapped between transactions.  Note that it does not affect the amount 
  185. // of backing store that may be mapped during the course of a transaction. A 
  186. // size of zero indicates that the resident size is unlimited.
  187.  
  188. - setSizeLimit:(vm_size_t)limit;
  189. - (vm_size_t)sizeLimit;
  190.  
  191. - (vm_size_t)apparentSize; // size of the backing store's virtual address space
  192. - (vm_size_t)residentSize; // the amount of backing store that is mapped
  193.  
  194. // These two methods create and install virtual memory images of stores; this 
  195. // is the most efficient way to copy stores.  The images are virtual memory 
  196. // snap shots; if a store is modified after an image is created, the image will 
  197. // diverge from the store via copy- on- write.
  198.  
  199. - getContents:(vm_address_t *)data andLength:(vm_size_t *)length;
  200. - setContents:(vm_address_t)data andLength:(vm_size_t)length;
  201.  
  202. // This is a cover for the two preceding methods for copying one store to another.
  203. - copyFromStore:(IXStore *)aStore;
  204.  
  205. @end
  206.  
  207.