storage.cs

Perst开源实时数据库

#if USE_GENERICS
        /// <summary>
        /// Create new generic set of objects
        /// </summary>
        /// <returns>
        /// empty set of persistent objects
        /// </returns>
        ISet<IPersistent> CreateSet();
        
        /// <summary>
        /// Create new generic link
        /// </summary>
        /// <returns>
        /// link of IPersistent references
        /// </returns>
        Link<IPersistent> CreateLink();
		
        /// <summary>
        /// Create new generic link with specified initial size
        /// </summary>
        /// <param name="initialSize">Initial link size</param>
        /// <returns>
        /// link of IPersistent references
        /// </returns>
        Link<IPersistent> CreateLink(int initialSize);

        /// <summary>
		/// Create new generic array of reference
        /// </summary>
        /// <returns>
        /// array of IPersistent references
        /// </returns>
        PArray<IPersistent> CreateArray();
		
        /// <summary>
		/// Create new generic array of reference
        /// </summary>
        /// <param name="initialSize">Initial array size</param>
        /// <returns>
        /// array of IPersistent references
        /// </returns>
        PArray<IPersistent> CreateArray(int initialSize);
#endif		


        /// <summary> Commit transaction (if needed) and close the storage
        /// </summary>
        void  Close();

        /// <summary> Set threshold for initiation of garbage collection. By default garbage collection is disable (threshold is set to
        /// Int64.MaxValue). If it is set to the value different fro Long.MAX_VALUE, GC will be started each time when
        /// delta between total size of allocated and deallocated objects exceeds specified threashold OR
        /// after reaching end of allocation bitmap in allocator. 
        /// </summary>
        /// <param name="allocatedDelta"> delta between total size of allocated and deallocated object since last GC or storage opening
        /// </param>
        ///
        void SetGcThreshold(long allocatedDelta);

        /// <summary>Explicit start of garbage collector
        /// </summary>
        /// <returns>number of collected (deallocated) objects</returns>
        /// 
        int Gc();

        /// <summary> Export database in XML format 
        /// </summary>
        /// <param name="writer">writer for generated XML document
        /// 
        /// </param>
        void  ExportXML(System.IO.StreamWriter writer);
		
        /// <summary> Import data from XML file
        /// </summary>
        /// <param name="reader">XML document reader
        /// 
        /// </param>
        void  ImportXML(System.IO.StreamReader reader);
		
        		
        /// <summary> 
        /// Retrieve object by OID. This method should be used with care because
        /// if object is deallocated, its OID can be reused. In this case
        /// getObjectByOID will return reference to the new object with may be
        /// different type.
        /// </summary>
        /// <param name="oid">object oid</param>
        /// <returns>reference to the object with specified OID</returns>
        IPersistent GetObjectByOID(int oid);

        /// <summary> 
        /// Explicitely make object peristent. Usually objects are made persistent
        /// implicitlely using "persistency on reachability apporach", but this
        /// method allows to do it explicitly. If object is already persistent, execution of
        /// this method has no effect.
        /// </summary>
        /// <param name="obj">object to be made persistent</param>
        /// <returns>OID assigned to the object</returns>
        int MakePersistent(IPersistent obj);

        ///
        /// <summary>
        /// Set database property. This method should be invoked before opening database. 
        /// </summary>
        /// <remarks> 
        /// Currently the following boolean properties are supported:
        /// <TABLE><TR><TH>Property name</TH><TH>Parameter type</TH><TH>Default value</TH><TH>Description</TH></TR>
        /// <TR><TD><code>perst.serialize.transient.objects</code></TD><TD>bool</TD><TD>false</TD>
        /// <TD>Serialize any class not derived from IPersistent or IValue using standard Java serialization
        /// mechanism. Packed object closure is stored in database as byte array. Latter the same mechanism is used
        /// to unpack the objects. To be able to use this mechanism, object and all objects referenced from it
        /// should be marked with Serializable attribute and should not contain references
        /// to persistent objects. If such object is referenced from N persistent object, N instances of this object
        /// will be stored in the database and after loading there will be N instances in memory.
        /// </TD></TR>
        /// <TR><TD><code>perst.object.cache.init.size</code></TD><TD>int</TD><TD>1319</TD>
        /// <TD>Initial size of object cache
        /// </TD></TR>
        /// <TR><TD><code>perst.object.cache.kind</code></TD><TD>String</TD><TD>"lru"</TD>
        /// <TD>Kind of object cache. The following values are supported:
        /// "strong", "weak", "pinned", "lru". <B>Strong</B> cache uses strong (normal)                                                                         
        /// references to refer persistent objects. Thus none of loaded persistent objects                                                                                                                                         
        /// can be deallocated by GC. It is possible to explicitely clear object cache using 
        /// <code>Storage.ClearObjectCache()</code> method. <B>Weak</B> and <b>lru</b> caches use weak references. 
        /// But <b>lru</b> cache also pin some number of recently used objects.
        /// Pinned object cache pin in memory all modified objects while using weak referenced for 
        /// non-modified objects. This kind of cache eliminate need in finalization mechanism - all modified
        /// objects are kept in memory and are flushed to the disk only at the end of transaction. 
        /// So the size of transaction is limited by amount of main memory. Non-modified objects are accessed only 
        /// through weak references so them are not protected from GC and can be thrown away.
        /// </TD></TR>
        /// <TR><TD><code>perst.object.index.init.size</code></TD><TD>int</TD><TD>1024</TD>
        /// <TD>Initial size of object index (specifying large value increase initial size of database, but reduce
        /// number of index reallocations)
        /// </TD></TR>
        /// <TR><TD><code>perst.extension.quantum</code></TD><TD>long</TD><TD>1048576</TD>
        /// <TD>Object allocation bitmap extension quantum. Memory is allocate by scanning bitmap. If there is no
        /// large enough hole, then database is extended by the value of dbDefaultExtensionQuantum. 
        /// This parameter should not be smaller than 64Kb.
        /// </TD></TR>
        /// <TR><TD><code>perst.gc.threshold</code></TD><TD>long</TD><TD>long.MaxValue</TD>
        /// <TD>Threshold for initiation of garbage collection. 
        /// If it is set to the value different from long.MaxValue, GC will be started each time 
        /// when delta between total size of allocated and deallocated objects exceeds specified threashold OR                                                                                                                                                                                                                           
        /// after reaching end of allocation bitmap in allocator.
        /// </TD></TR>
        /// <TR><TD><code>perst.code.generation</code></TD><TD>string</TD><TD>async</TD>
        /// <TD>enable or disable dynamic generation of pack/unpack methods for persistent 
        /// classes. Such methods can be generated only for classes with public fields.
        /// Using generated methods instead of .Net reflection API increase speed of
        /// object store/fetch operations, but generation itself takes additional time at 
        /// startup. This parameter can have three values: "sync", "async" (or "true") and 
        /// "disabled" (or "false"). In case of asynchronous methods generation,
        /// it is performed by background thread with low priority. It has minimal influence on
        /// database open time, but if large of the objects are loaded from the database
        /// immediately after database open, then pack.unpack methods may not be ready and
        /// so loading of database takes a longer time.
        /// Synchronous methods inside Storage.Open method. So it can increase time of 
        /// opening database (especially if there are large number of classes in database)
        /// but in this case all pack/unpack methods will be ready after return from Open method.
        /// If runtime code generation is disabled, then no methods are generated.
        /// Runtime code generation is not supported and so is disabled at Compact.Net platform.
        /// </TD></TR>
        /// <TR><TD><code>perst.file.readonly</code></TD><TD>bool</TD><TD>false</TD>
        /// <TD>Database file should be opened in read-only mode.
        /// </TD></TR>
        /// <TR><TD><code>perst.lock.file</code></TD><TD>bool</TD><TD>true</TD>
        /// <TD>Lock database file to prevent concurrent access to the database by 
        ///  more than one application.
        /// </TD></TR>
        /// <TR><TD><code>perst.file.noflush</code></TD><TD>bool</TD><TD>false</TD>
        /// <TD>To not flush file during transaction commit. It will greatly increase performance because
        /// eliminate synchronous write to the disk (when program has to wait until all changed
        /// are actually written to the disk). But it can cause database corruption in case of 
        /// OS or power failure (but abnormal termination of application itself should not cause
        /// the problem, because all data which were written to the file, but is not yet saved to the disk is 
        /// stored in OS file buffers and sooner or later them will be written to the disk)
        /// </TD></TR>
        /// <TR><TD><code>perst.alternative.btree</code></TD><TD>bool</TD><TD>false</TD>
        /// <TD>Use aternative implementation of B-Tree (not using direct access to database
        /// file pages). This implementation should be used in case of serialized per thread transctions.
        /// New implementation of B-Tree will be used instead of old implementation
        /// if "perst.alternative.btree" property is set. New B-Tree has incompatible format with 
        /// old B-Tree, so you could not use old database or XML export file with new indices. 
        /// Alternative B-Tree is needed to provide serializable transaction (old one could not be used).
        /// Also it provides better performance (about 3 times comaring with old implementation) because
        /// of object caching. And B-Tree supports keys of user defined types. 
        /// </TD></TR>
        /// <TR><TD><code>perst.background.gc</code></TD><TD>bool</TD><TD>false</TD>
        /// <TD>Perform garbage collection in separate thread without blocking the main application.                                                                                          
        /// </TD></TR>
        /// <TR><TD><code>perst.string.encoding</code></TD><TD>String</TD><TD>null</TD>
        /// <TD>Specifies encoding of storing strings in the database. By default Perst stores 
        /// strings as sequence of chars (two bytes per char). If all strings in application are in 
        /// the same language, then using encoding  can signifficantly reduce space needed
        /// to store string (about two times). But please notice, that this option has influence
        /// on all strings  stored in database. So if you already have some data in the storage
        /// and then change encoding, then it can cause incorrect fetching of strings and even database crash.
        /// </TD></TR>
        /// <TR><TD><code>perst.replication.ack</code></TD><TD>Boolean</TD><TD>false</TD>
        /// <TD>Request acknowledgement from slave that it receives all data before transaction
        /// commit. If this option is not set, then replication master node just writes
        /// data to the socket not warring whether it reaches slave node or not.
        /// When this option is set to true, master not will wait during each transaction commit acknowledgement
        /// from slave node. Please notice that this option should be either set or not set both
        /// at slave and master node. If it is set only on one of this nodes then behavior of
        /// the system is unpredicted. This option can be used both in synchronous and asynchronous replication
        /// mode. The only difference is that in first case main application thread will be blocked waiting
        /// for acknowledgment, while in the asynchronous mode special replication thread will be blocked
        /// allowing thread performing commit to proceed.
        /// </TD></TR>
        /// <TR><TD><code>perst.concurrent.iterator</code></TD><TD>bool</TD><TD>false</TD>
        /// <TD>By default iterator will throw ConcurrentModificationException if iterated collection
        /// was changed outside iterator, when the value of this property is true then iterator will 
        /// try to restore current position and continue iteration
        /// </TD></TR>
        /// <TR><TD><code>perst.slave.connection.timeout</code></TD><TD>int</TD><TD>60</TD>
        /// <TD>Timeout in seconds during which mastr node will try to establish connection with slave node. 
        /// If connection can not be established within specified time, then master will not perform 
        /// replication to this slave node
        /// </TD></TR>
        /// <TR><TD><code>perst.page.pool.lru.limit</code></TD><TD>long</TD><TD>1L &lt;&lt; 60</TD>
        /// <TD>Set boundary for caching database pages in page pool. 
        /// By default Perst is using LRU algorithm for finding candidate for replacement.
        /// But for example for BLOBs this strategy is not optimal and fetching BLOB can
        /// cause flushing the whole page pool if LRU discipline is used. And with high
        /// probability fetched BLOB pages will no be used any more. So it is preferable not
        /// to cache BLOB pages at all (throw away such page immediately when it is not used any more).
        /// This parameter in conjunction with custom allocator allows to disable caching
        /// for BLOB objects. If you set value of "perst.page.lru.scope" property equal
        /// to base address of custom allocator (which will be used to allocate BLOBs), 
        /// then page containing objects allocated by this allocator will not be cached in page pool.
        /// </TD></TR>
        /// </TABLE>
        /// </remarks>