Interface IPile

Represents a pile of objects - a custom memory heap that can store native CLR objects in a tightly-serialized form. Piles can be either local (allocate local RAM on the server), or distributed (allocate RAM on many servers). This class is designed primarily for applications that need to store/cache very many (100s of millions on local, billions on distributed) of objects in RAM (and/or possibly on disk) without causing the local CLR's GC scans of huge object graphs. Implementors of this interface are custom memory managers that favor the GC performance in apps with many objects at the cost of higher CPU usage. The implementor must be thread-safe for all operations unless stated otherwise on a member level. The memory represented by this class as a whole is not synchronizable, that is - it does not support functions like Interlocked-family, Lock, MemoryBarriers and the like that regular RAM supports. Should a need arise to interlock within the pile - a custom CLR-based lock must be used to syncronize access to pile as a whole, for example: a Get does not impose a lock on ALL concurrent writes throught the pile (a write does not block all gets either). The enumeration of the pile is thread-safe, however it does not guarantee the snapshot stability as parallel mutations may happen while enumeration takes place.

Inherited Members
System.Collections.Generic.IEnumerable<Azos.Pile.PileEntry>.GetEnumerator()
Namespace: Azos.Pile
Assembly: Azos.dll
Syntax
public interface IPile : IPileStatus, IEnumerable<PileEntry>, IEnumerable, IApplicationComponent

Methods

Compact()

Tries to delete extra capacity which is allocated but not currently needed. Returns the number of bytes freed back to the system

Declaration
long Compact()
Returns
Type Description
System.Int64

Delete(PilePointer, Boolean)

Deletes object from pile by its pointer returning true if there is no access violation and pointer is pointing to the valid object, throws otherwise unless throwInvalid is set to false

Declaration
bool Delete(PilePointer ptr, bool throwInvalid = true)
Parameters
Type Name Description
PilePointer ptr
System.Boolean throwInvalid
Returns
Type Description
System.Boolean

Get(PilePointer)

Returns a CLR object by its pointer or throws access violation if pointer is invalid

Declaration
object Get(PilePointer ptr)
Parameters
Type Name Description
PilePointer ptr
Returns
Type Description
System.Object

GetRawBuffer(PilePointer, out Byte)

Returns a raw byte[] occupied by the object payload, only payload is returned along with serializer flag which tells what kind of serializer was used. This method is rarely used, it is needed for debugging and special-case "direct" memory access on read to bypass the de-serialization process altogether

Declaration
byte[] GetRawBuffer(PilePointer ptr, out byte serializerFlag)
Parameters
Type Name Description
PilePointer ptr
System.Byte serializerFlag
Returns
Type Description
System.Byte[]

Purge()

Deletes all objects freeing all segment memory buffers. This method may require the caller to have special rights

Declaration
void Purge()

Put(PilePointer, Object, UInt32, Boolean)

Tries to put the new object over an existing one at the pre-define position. The pointer has to reference a valid allocated block. If object fits in the allocated block returns true, otherwise tries to create an internal link to the new pointer which is completely transparent to the caller. The linking may be explicitly disabled in which case the method returns false when the new object does not fit into the existing block

Declaration
bool Put(PilePointer ptr, object obj, uint lifeSpanSec = 0U, bool link = true)
Parameters
Type Name Description
PilePointer ptr

The pointer to the existing valid allocated block
System.Object obj

A new/modified CLR object to put into the Pile over an existing one
System.UInt32 lifeSpanSec

Optional lifeSpanSec will auto-delete object after the interval elapses if the pile SupportsObjectExpiration and SweepExpiredObjects is set to true
System.Boolean link

False to prohibit internal pointer linking
Returns
Type Description
System.Boolean

True if object was inserted, false otherwise (i.e. when linking is false)

Put(Object, UInt32, Int32)

Puts a CLR object into the pile and returns a newly-allocated pointer. Throws out-of-space if there is not enough space in the pile and limits are set. Optionally takes lifeSpan (if Pile supports it) and extra preallocation bytes

Declaration
PilePointer Put(object obj, uint lifeSpanSec = 0U, int preallocateBlockSize = 0)
Parameters
Type Name Description
System.Object obj

CLR object to put into the Pile
System.UInt32 lifeSpanSec

Optional lifeSpanSec will auto-delete object after the interval elapses if the pile SupportsObjectExpiration and SweepExpiredObjects is set to true
System.Int32 preallocateBlockSize

When specified, adds extra space to the allocated block so that the object can be changed in-place without creating the link. Specifies the total size of the block in bytes. If this size is less than actual object payload then allocates the block of the payload size
Returns
Type Description
PilePointer

Rejuvenate(PilePointer)

If pile supports expiration, resets object age to zero. Returns true if object was found and reset. N/A for pile that do not support expiration

Declaration
bool Rejuvenate(PilePointer ptr)
Parameters
Type Name Description
PilePointer ptr
Returns
Type Description
System.Boolean

SizeOf(PilePointer)

Returns the size of pointed-to object in bytes or throws access violation if pointer is invalid. The serialized object size is returned, not the CLR object size.

Declaration
int SizeOf(PilePointer ptr)
Parameters
Type Name Description
PilePointer ptr
Returns
Type Description
System.Int32

Extension Methods