Permalink
Switch branches/tags
Nothing to show
Find file Copy path
9fca1a4 Jan 17, 2018
1 contributor

Users who have contributed to this file

245 lines (201 sloc) 9.78 KB
/*<FILE_LICENSE>
* NFX (.NET Framework Extension) Unistack Library
* Copyright 2003-2018 Agnicore Inc. portions ITAdapter Corp. Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
</FILE_LICENSE>*/
/*
* Author: Dmitriy Khmaladze, Spring 2015 dmitriy@itadapter.com
*/
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using NFX.Environment;
using NFX.Instrumentation;
namespace NFX.ApplicationModel.Pile
{
/// <summary>
/// Provides information about the pile - number of objects, allocated bytes, etc.
/// </summary>
public interface IPileStatus
{
/// <summary>
/// Returns a node-global ID of this pile instance
/// </summary>
int Identity { get;}
/// <summary>
/// Returns whether pile is local or distributed
/// </summary>
LocalityKind Locality { get;}
/// <summary>
/// Returns the model of object persistence that this pile supports
/// </summary>
ObjectPersistence Persistence { get;}
/// <summary>
/// Returns whether this instance supports object expiration
/// </summary>
bool SupportsObjectExpiration{ get;}
/// <summary>
/// Returns the number of allocated objects in this pile
/// </summary>
long ObjectCount{ get;}
/// <summary>
/// Returns the number of allocated object links in this pile.
/// Links are used to chain existing location to another one when larger payload does not fit
/// at the progonal location
/// </summary>
long ObjectLinkCount{ get;}
/// <summary>
/// Returns the number of bytes allocated by this pile from system memory
/// </summary>
long AllocatedMemoryBytes{ get;}
/// <summary>
/// Returns an approximate capacity of free memory that the system has left
/// </summary>
long MemoryCapacityBytes{ get;}
/// <summary>
/// Returns the number of bytes allocated for object storage within AllocatedMemoryBytes
/// </summary>
long UtilizedBytes{ get;}
/// <summary>
/// Returns the number of extra bytes used by pile metadata currently occupied by object stored in this pile
/// </summary>
long OverheadBytes { get; }
/// <summary>
/// Returns the number of segments allocated
/// </summary>
long SegmentCount { get;}
/// <summary>
/// Returns the number of nodes(servers) that service this distributed pile.
/// If this pile locality is local then returns 1
/// </summary>
int NodeCount { get;}
}
/// <summary>
/// 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.
/// </summary>
public interface IPile : IPileStatus, IEnumerable<PileEntry>, IApplicationComponent
{
/// <summary>
/// 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
/// </summary>
/// <param name="obj">CLR object to put into the Pile</param>
/// <param name="lifeSpanSec">
/// Optional lifeSpanSec will auto-delete object after the interval elapses if
/// the pile SupportsObjectExpiration and SweepExpiredObjects is set to true
/// </param>
/// <param name="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
/// </param>
// <returns>a new PilePointer pointing at the stored payload</returns>
PilePointer Put(object obj, uint lifeSpanSec = 0, int preallocateBlockSize = 0);
/// <summary>
/// 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
/// </summary>
/// <param name="obj">A new/modified CLR object to put into the Pile over an existing one</param>
/// <param name="lifeSpanSec">
/// Optional lifeSpanSec will auto-delete object after the interval elapses if
/// the pile SupportsObjectExpiration and SweepExpiredObjects is set to true
/// </param>
/// <param name="ptr">The pointer to the existing valid allocated block</param>
/// <param name="link">False to prohibit internal pointer linking</param>
/// <returns>True if object was inserted, false otherwise (i.e. when linking is false)</returns>
bool Put(PilePointer ptr, object obj, uint lifeSpanSec = 0, bool link = true);
/// <summary>
/// Returns a CLR object by its pointer or throws access violation if pointer is invalid
/// </summary>
object Get(PilePointer ptr);
/// <summary>
/// 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
/// </summary>
byte[] GetRawBuffer(PilePointer ptr, out byte serializerFlag);
/// <summary>
/// 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
/// </summary>
bool Delete(PilePointer ptr, bool throwInvalid = true);
/// <summary>
/// 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
/// </summary>
bool Rejuvenate(PilePointer ptr);
/// <summary>
/// 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.
/// </summary>
int SizeOf(PilePointer ptr);
/// <summary>
/// Deletes all objects freeing all segment memory buffers.
/// This method may require the caller to have special rights
/// </summary>
void Purge();
/// <summary>
/// Tries to delete extra capacity which is allocated but not currently needed.
/// Returns the number of bytes freed back to the system
/// </summary>
long Compact();
}
public interface IPileImplementation : IPile, ServiceModel.IService, IInstrumentable
{
/// <summary>
/// Defines modes of allocation: space/time tradeoff
/// </summary>
AllocationMode AllocMode{ get; set;}
/// <summary>
/// Control whether the instance respects object life spans
/// if they are set
/// </summary>
bool SweepExpiredObjects{ get; set;}
/// <summary>
/// Imposes a limit on maximum number of bytes that a pile can allocate of the system heap.
/// The default value of 0 means no limit, meaning - the pile will keep allocating objects
/// until the system allows
/// </summary>
long MaxMemoryLimit { get; set;}
/// <summary>
/// Gets the maximum count of segments that this pile can have.
/// The property is not thread-safe for set and can only be set if pile is inactive.
/// The value of zero means no limit
/// </summary>
int MaxSegmentLimit { get; set;}
/// <summary>
/// Gets the segment size in bytes, up to (2^31)-1
/// The property is not thread-safe for set and can only be set if pile is inactive
/// </summary>
int SegmentSize { get; set;}
}
}