storage.cs

Perst开源实时数据库

        /// <param name="name">name of the property</param>
        /// <param name="val">value of the property</param>
        ///
        void SetProperty(string name, object val);

        ///
        /// <summary>Set database properties. This method should be invoked before opening database. 
        /// For list of supported properties please see <see cref="SetProperty">setProperty</see>. 
        /// All not recognized properties are ignored.
        /// </summary>
        /// <param name="props">collections with storage properties</param>
        ///
        void SetProperties(Hashtable props);

        ///
        /// <summary>Get property value.
        /// </summary>
        /// <param name="name">property name</param>
        /// <returns>value of the property previously assigned by setProperty or setProperties method
        /// or <code>null</code> if property was not set
        /// </returns>
        ///
        object GetProperty(string name);

        ///
        /// <summary>
        /// Get all set properties
        /// </summary>
        /// <returns>all properties set by setProperty or setProperties method
        /// </returns>
        ///
        Hashtable GetProperties();
 
        /// <summary>
        /// Merge results of several index searches. This method efficiently merge selections without loading objects themselve
        /// </summary>
        /// <param name="selections">Selections to be merged</param>
        /// <returns>Enumerator through merged result</returns>
#if USE_GENERICS
        IEnumerator<T> Merge<T>(IEnumerator<T>[] selections) where T:class,IPersistent;
#else
        IEnumerator Merge(IEnumerator[] selections);
#endif

        /// <summary>
        /// Join results of several index searches. This method efficiently join selections without loading objects themselve
        /// </summary>
        /// <param name="selections">Selections to be joined</param>
        /// <returns>Enumerator through joined result</returns>
#if USE_GENERICS
        IEnumerator<T> Join<T>(IEnumerator<T>[] selections) where T:class,IPersistent;
#else
        IEnumerator Join(IEnumerator[] selections);
#endif
        /// <summary>
        /// Set storage listener.
        /// </summary>summary>
        /// <param name="listener">new storage listener (may be null)</param>
        /// <returns>previous storage listener</returns>
        ///
        StorageListener SetListener(StorageListener listener);

        /// <summary>
        /// Set class loader. This class loader will be used to locate classes for 
        /// loaded class descriptors. If class loader is not specified or
        /// it did find the class, then class will be searched in all active assemblies
        /// </summary>
        ClassLoader Loader {get; set;}


#if COMPACT_NET_FRAMEWORK
        /// <summary>
        /// Compact.NET framework doesn;t allow to get list of assemblies loaded
        /// in application domain. Without it I do not know how to locate
        /// class from foreign assembly by name. 
        /// Assembly which creates Storare is automatically registered.
        /// Other assemblies has to explicitely registered by programmer.
        /// </summary>
        /// <param name="assembly">registered assembly</param>
        void RegisterAssembly(System.Reflection.Assembly assembly);
#else
        /// <summary>
        /// Create persistent class wrapper. This wrapper will implement virtual properties
        /// defined in specified class or interface, performing transparent loading and storing of persistent object
        /// </summary>
        /// <param name="type">Class or interface type of instantiated object</param>
        /// <returns>Wrapper for the specified class, implementing all virtual properties defined
        /// in it
        /// </returns>
        IPersistent CreateClass(Type type);
#endif

        /// <summary>
        /// Begin per-thread transaction. Three types of per-thread transactions are supported: 
        /// exclusive, cooperative and serializable. In case of exclusive transaction, only one 
        /// thread can update the database. In cooperative mode, multiple transaction can work 
        /// concurrently and commit() method will be invoked only when transactions of all threads
        /// are terminated. Serializable transactions can also work concurrently. But unlike
        /// cooperative transaction, the threads are isolated from each other. Each thread
        /// has its own associated set of modified objects and committing the transaction will cause
        /// saving only of these objects to the database.To synchronize access to the objects
        /// in case of serializable transaction programmer should use lock methods
        /// of IResource interface. Shared lock should be set before read access to any object, 
        /// and exclusive lock - before write access. Locks will be automatically released when
        /// transaction is committed (so programmer should not explicitly invoke unlock method)
        /// In this case it is guaranteed that transactions are serializable.
        /// It is not possible to use <code>IPersistent.store()</code> method in
        /// serializable transactions. That is why it is also not possible to use Index and FieldIndex
        /// containers (since them are based on B-Tree and B-Tree directly access database pages
        /// and use <code>store()</code> method to assign OID to inserted object. 
        /// You should use <code>SortedCollection</code> based on T-Tree instead or alternative
        /// B-Tree implemenataion (set "perst.alternative.btree" property).
        /// </summary>
        /// <param name="mode"><code>TransactionMode.Exclusive</code>,  <code>TransactionMode.Cooperative</code>,
        /// <code>TransactionMode.ReplicationSlave</code> or <code>TransactionMode.Serializable</code>
        /// </param>
        void BeginThreadTransaction(TransactionMode mode);
    
        /// <summary>
        /// End per-thread transaction started by beginThreadTransaction method.
        /// <ul>
        /// <li>If transaction is <i>exclusive</i>, this method commits the transaction and
        /// allows other thread to proceed.</li><li>
        /// If transaction is <i>serializable</i>, this method commits sll changes done by this thread
        /// and release all locks set by this thread.</li><li>     
        /// If transaction is <i>cooperative</i>, this method decrement counter of cooperative
        /// transactions and if it becomes zero - commit the work</li></ul>
        /// </summary>
        void EndThreadTransaction();

        /// <summary>
        /// End per-thread cooperative transaction with specified maximal delay of transaction
        /// commit. When cooperative transaction is ended, data is not immediately committed to the
        /// disk (because other cooperative transaction can be active at this moment of time).
        /// Instead of it cooperative transaction counter is decremented. Commit is performed
        /// only when this counter reaches zero value. But in case of heavy load there can be a lot of
        /// requests and so a lot of active cooperative transactions. So transaction counter never reaches zero value.
        /// If system crash happens a large amount of work will be lost in this case. 
        /// To prevent such scenario, it is possible to specify maximal delay of pending transaction commit.
        /// In this case when such timeout is expired, new cooperative transaction will be blocked until
        /// transaction is committed.
        /// </summary>
        /// <param name="maxDelay">maximal delay in milliseconds of committing transaction.  Please notice, that Perst could 
        /// not force other threads to commit their cooperative transactions when this timeout is expired. It will only
        /// block new cooperative transactions to make it possible to current transaction to complete their work.
        /// If <code>maxDelay</code> is 0, current thread will be blocked until all other cooperative trasnaction are also finished
        /// and changhes will be committed to the database.
        /// </param>
        void EndThreadTransaction(int maxDelay);
   
        /// <summary>
        /// Rollback per-thread transaction. It is safe to use this method only for exclusive transactions.
        /// In case of cooperative transactions, this method rollback results of all transactions.
        /// </summary>
        void RollbackThreadTransaction();

        /// <summary>
        /// Get database memory dump. This function returns hashmap which key is classes
        /// of stored objects and value - MemoryUsage object which specifies number of instances
        /// of particular class in the storage and total size of memory used by these instance.
        /// Size of internal database structures (object index, memory allocation bitmap) is associated with 
        /// <code>Storage</code> class. Size of class descriptors  - with <code>System.Type</code> class.
        /// <p>This method traverse the storage as garbage collection do - starting from the root object
        /// and recursively visiting all reachable objects. So it reports statistic only for visible objects.
        /// If total database size is significantly larger than total size of all instances reported
        /// by this method, it means that there is garbage in the database. You can explicitly invoke
        /// garbage collector in this case.</p> 
        /// </summary>
        Hashtable GetMemoryDump();

        /// <summary>
        /// Get total size of all allocated objects in the database
        /// </summary>
        long UsedSize {get;}

        /// <summary>
        /// Get size of the database
        /// </summary>
        long DatabaseSize {get;}

        /// <summary>
        /// Register custom allocator for specified class. Instances of this and derived classes 
        /// will be allocated in the storage using specified allocator. 
        /// </summary>
        /// <param name="cls">class of the persistent object which instances will be allocated using this allocator</param>
        /// <param name="allocator">custom allocator</param>
        void RegisterCustomAllocator(Type cls, CustomAllocator allocator);

        /// <summary>
        /// Create bitmap custom allocator
        /// </summary>
        /// <param name="quantum">size in bytes of allocation quantum. Should be power of two.</param>
        /// <param name="baseAddr">base address for allocator (it should match offset of multifile segment)</param>
        /// <param name="extension">size by which space mapped by allocator is extended each time when 
        /// no suitable hole is found in bitmap (it should be large enough to improve allocation speed and locality                                                                                                     
        /// of references)</param>
        /// <param name="limit">maximal size of memory allocated by this allocator (pass Long.MAX_VALUE if you do not 
        /// want to limit space)</param>
        /// <returns> created allocator</returns>
        CustomAllocator CreateBitmapAllocator(int quantum, long baseAddr, long extension, long limit);

        /// <summary>
        /// Set custom serializer used fot packing/unpacking fields of persistent objects which types implemplemet 
        /// CustomSerializable interface
        /// </summary>
        void SetCustomSerializer(CustomSerializer serializer);

        /// <summary>
        /// Clear database object cache. This method can be used with "strong" object cache to avoid memory overflow.
        /// It is no valid to invoke this method when there are some uncommitted changes in the database
        /// (some modified objects). Also all variables containing references to persistent object should be reset after
        /// invocation of this method - it is not correct to accessed object directly though such variables, objects
        /// has to be reloaded from the storage
        /// </summary>
        void ClearObjectCache();


        // Internal methods
		
        void  deallocateObject(IPersistent obj);
		
        void  storeObject(IPersistent obj);
		
        void  storeFinalizedObject(IPersistent obj);
		
        void  loadObject(IPersistent obj);
		
        void  modifyObject(IPersistent obj);

        bool  lockObject(IPersistent obj);
    }
}