Shared Persistent Heap, logger. For shared memory multi-thread/multi-core applications. This implementation uses atomic operations to implement Lock Free Loggers (SPHLFLogger_t). More...

#include "sastype.h"
#include "sphtimer.h"

Classes
struct	sphLogEntryLayout_t
	sphLogEntry_t. Fields defining the entry details word. More...

union	sphLogEntry_t
	Union of Entry details with 32-bit word for atomic update. More...

struct	SPHLFLogHeader_t
	Instance of a Lock Free Logger Entry Header. More...

struct	SPHLFLoggerHandle_t
	Instance of a Lock Free Logger Entry Handle. More...

struct	SPHLFLogIterator_t
	Instance of a Lock Free Logger Iterator. More...

Macros
#define	__C__
	ignore this macro behined the curtain

#define	SPHLFLOGGER_CIRCULAR (1)
	internal options flag for circular log buffers

#define	SPHLFLOGGER_CIRCULAR_WRAPED (1<<1)
	internal options flag set when circular log buffers have wrapped

#define	SPHLFLOGGER_CIRCULAR_NOTFIRST (1<<2)
	internal options flag set when circular log buffers have wrapped multiple times

#define	SPHLFLOGGER_CACHE_PREFETCH0 (1<<3)
	internal options flag for prefetching the immediate (0 offset) cache-line

#define	SPHLFLOGGER_CACHE_PREFETCH1 (1<<4)
	internal options flag for prefetching the next (line size offset) cache-line

#define	SPHLFLOGGER_CIRCULAR_RESETMASK
	internal options mask flag used the reset circular log buffers More...

Typedefs
typedef void *	SPHLFLogger_t
	Handle to an instance of SPH Lock Free Logger. More...

typedef unsigned long	longPtr_t
	unsigned int type, consistent with the size of a pointer and used for pointer calculations

typedef unsigned int	sphLogEntryID_t
	Aggregate type for handling sphLogEntryLayout_t.

typedef unsigned short	sphpid16_t
	Common type for PID/TID values stored in Logger entries.

Functions
__C__ SPHLFLogger_t	SPHLFLoggerInit (void *buf_seg, block_size_t buf_size)
	Initialize a shared storage block as a Lock Free Event Logger. More...

__C__ SPHLFLogger_t	SPHLFLoggerInitWithStride (void *buf_seg, block_size_t buf_size, unsigned short entry_stride, unsigned int options)
	Initialize a shared storage block as a Lock Free Event Logger with a fixed entry stride. More...

__C__ SPHLFLogger_t	SPHLFLoggerCreate (block_size_t buf_size)
	Allocate and initialize a shared storage block as a Lock Free Event Logger. More...

__C__ SPHLFLogger_t	SPHLFCircularLoggerCreate (block_size_t buf_size, unsigned short stride)
	Allocate and initialize a shared storage block as a Lock Free Event Logger. Mark the logger as circular and specify a fixed Stride. More...

__C__ void *	SPHLFLoggerAllocRaw (SPHLFLogger_t log, block_size_t alloc_size)
	Return the address of a (raw) Logger entry allocated from the specified logger. More...

__C__ SPHLFLoggerHandle_t *	SPHLFLoggerAllocTimeStamped (SPHLFLogger_t log, int catcode, int subcode, block_size_t alloc_size, SPHLFLoggerHandle_t *handlespace)
	Allocate and initialize the header, of a timestamped logger entry, from the specified logger. More...

__C__ SPHLFLoggerHandle_t *	SPHLFLoggerAllocStrideTimeStamped (SPHLFLogger_t log, int catcode, int subcode, SPHLFLoggerHandle_t *handlespace)
	Allocate and initialize the header, of a timestamped logger entry, from the specified logger. More...

__C__ SPHLFLoggerHandle_t *	SPHLFLoggerAllocTimeStampedNoLock (SPHLFLogger_t log, int catcode, int subcode, block_size_t alloc_size, SPHLFLoggerHandle_t *handlespace)
	Allocate and initialize the header of a timestamped logger entry from the specified logger, without locking or memory barriers. More...

__C__ SPHLFLoggerHandle_t *	SPHLFLoggerAllocStrideTimeStampedNoLock (SPHLFLogger_t log, int catcode, int subcode, SPHLFLoggerHandle_t *handlespace)
	Allocate and initialize the header, of a timestamped logger entry, from the specified logger, without locking or memory barriers. More...

__C__ int	SPHLFLoggerEntryComplete (SPHLFLoggerHandle_t *entryhandle)
	Marks the entry specified by the entry handle as complete. More...

__C__ int	SPHLFLoggerEntryIsComplete (SPHLFLoggerHandle_t *entryhandle)
	Return the status of the entry specified by the entry handle. More...

__C__ int	SPHLFLoggerEntryIsTimestamped (SPHLFLoggerHandle_t *entryhandle)
	Return the status of the entry specified by the entry handle. More...

__C__ SPHLFLoggerHandle_t *	SPHLFLoggerIteratorNext (SPHLFLogIterator_t iterator, SPHLFLoggerHandle_t handlespace)
	For the provided Logger Iterator creates a entry handle for the next sequential Logger entry. The resulting entry handle can be used to read the contents of the Logger entry. More...

__C__ SPHLFLogIterator_t *	SPHLFLoggerCreateIterator (SPHLFLogger_t log, SPHLFLogIterator_t *iteratorSpace)
	Creates a logger Iterator for reading sequential entries from a specific logger. More...

__C__ int	SPHLFLoggerEmpty (SPHLFLogger_t log)
	Return the status of the specified logger. More...

__C__ int	SPHLFLoggerWrapped (SPHLFLogger_t log)
	Return the status of the specified logger. More...

__C__ block_size_t	SPHLFLoggerFreeSpace (SPHLFLogger_t log)
	Returns the amount of free space (in bytes) remaining in the specified logger. More...

__C__ int	SPHLFLoggerFull (SPHLFLogger_t log)
	Return the status of the specified logger. More...

__C__ int	SPHLFLoggerResetIfFullSync (SPHLFLogger_t log)
	Resets the specific logger to empty state synchronously if it is currently full. More...

__C__ int	SPHLFLoggerResetAsync (SPHLFLogger_t log)
	Resets the specific logger to empty state asynchronously (without locking or atomic updates). More...

__C__ int	SPHLFLoggerPrefetch (SPHLFLogger_t log)
	Prefetch pages from the specific logger. More...

__C__ int	SPHLFLoggerSetCachePrefetch (SPHLFLogger_t log, int prefetch)
	Set the cache-line prefetch options for entry allocate. More...

__C__ int	SPHLFLoggerDestroy (SPHLFLogger_t log)
	Destroys the logger and frees the SAS storage for reuse. More...

Detailed Description

Shared Persistent Heap, logger. For shared memory multi-thread/multi-core applications. This implementation uses atomic operations to implement Lock Free Loggers (SPHLFLogger_t).

This Logger API supports atomic allocation of storage for event entries for zero copy persistence and sharing. Only the allocation of the entry is serialized. If there are multiple threads or processes generating log entries, on a multi-core processor, hardware threads can fill in Log entries in parallel with other threads.

The API support simple loggers and circular loggers. Simple loggers stop allocating entries when the log buffer is full. Circular loggers wrap to the beginning of the log buffer when the log buffer fills. This overwrites the oldest log entries. but allows logging on a continuous basis. Circular loggers use a fixed entry stride to insure the oldest entry can be found easily. A stride that matches the cache line size can improve performance by avoiding "false sharing" of cache lines containing multiple logger entries across cores/sockets.

For example:

SPHLFLogger_t logger;
SPHContext_t context;
SASJoinRegion();
// set up shared circular logger with fixed size entries
// Stride is a full cache line for better performance
logger = SPHLFCircularLoggerCreate (log_alloc, 128);
if ( logger )
{
    context = SPHSetupProjectContext ("myproject");
    if (context)
    {
        SPHContextAddName (context, "flight_recorder", logger)
    }
}

As an option the logger allocator will fill in a 16 byte
entry header with: \n Entry status and length.  \n Entry identifying
Category and SubCategory codes. \n Process and Thread Ids.  \n High
resolution timestamp.

SPHLFLogger_t logger;
SPHContext_t context;
SPHLFLoggerHandle_t *handlex, handle_data;
SASJoinRegion();
// get up shared circular logger
context getProjectContextByName ("myproject");
if (context)
{
   logger = (SPHLFLogger_t)SPHContextFindByName (context, "flight_recorder");
       ...
   // create a flight_recorder entry with application category/subcategory codes
   // with process/thread IDs and timestamp.
   if (logger)
   {
        handex = SPHLFLoggerAllocStrideTimeStamped (logger, category_x, subcat_y, handle_data);
        ...
   }
}

Any additional storage allocated to the entry
is available for application specific data.
The sphlflogentry.h API also provides
several mechanisms to store application data including; direct
array or structure overlay, and a streams like mechanism.
The API provides a completion function (SPHLFLoggerEntryComplete)
which provides any memory barriers required by the platform and
marks the entry complete.

...
// create a flight_recorder entry with application cat/subcat codes
// rumtime provides process/thread IDs and time_stamp.
handex = SPHLFLoggerAllocStrideTimeStamped (logger, category_x, subcat_y, handle_data);
if (handex)
{
    // insert a stream of application specific data
    SPHLFLogEntryAddInt(handlex, int_data1);
    SPHLFLogEntryAddInt(handlex, int_data2);
    SPHLFLogEntryAddPtr(handlex, ptr_1);
    SPHLFLogEntryAddDouble(handlex, double_data1);
    SPHLFLogEntryAddString(handlex, "any_c_string");
           ...
       // Insure the entry is coherent and mark this entry complete
       SPHLFLogEntryComplete (handlex);
}

The logger contents are shared and persistent and will not be lost if the logging process crashes. Logger entries can be retrieved at any time after it is marked complete.

The API provides Log Iterator functions that support sequential read-back
of (completed) Logger entries. First create a log iterator
(with SPHLFloggerCreateIterator). Then use the resulting iterator to
sequentially step through log entries (via SPHLFLoggerItertorNext).
The iterator runtime handles both simple and circular loggers and insures
entries are read-out (oldest to newest) in order.

SPHLFLogIterator_t *iter, iter0;
SPHLFLoggerHandle_t *handlex, handle_data;
...
// create a Log iterator over the flight recorder
iter = SPHLFLoggerCreateIterator(logger, &iter0);
if (iter)
{
    handlex = SPHLFLoggerIteratorNext (iter, &handle_data);
    while (handex)
    {
        sphtimer_t entry_timestamp;
        int cat, subcat, PID, TID:
        int int_data1, int_data1;
        void * ptr_1;
        double double_data1;
        char * entry_str;
        // extract entry data
        PID = SPHLFLogEntryPID (handlex);
        TID = SPHLFLogEntryTID (handlex);
        cat = SPHLFLogEntryCategory (handlex);
        subcat = SPHLFLogEntrySubcat (handlex);
        entry_timestamp = SPHLFLogEntryTimeStamp (handlex);
        ...
        // extract application specific data, in insertion order
        int_data1 = SPHLFLogEntryGetNextInt(handlex);
        int_data2 = SPHLFLogEntryGetNextInt(handlex);
        ptr_1 = SPHLFLogEntryGetNextPtr(handlex);
        double_data1 = SPHLFLogEntryGetNextDouble(handlex);
        entry_str SPHLFLogEntryGetNextString(handlex);
           ...
        // do something with the date
        ...
        // get next entry
        handlex = SPHLFLoggerIteratorNext (iter, &handle_data);
    }
}

Macro Definition Documentation

#define SPHLFLOGGER_CIRCULAR_RESETMASK

Value:

(SPHLFLOGGER_CIRCULAR | \
		SPHLFLOGGER_CACHE_PREFETCH0 | \
		SPHLFLOGGER_CACHE_PREFETCH1)

internal options mask flag used the reset circular log buffers

Typedef Documentation

typedef void* SPHLFLogger_t

Handle to an instance of SPH Lock Free Logger.

The type is SAS_RUNTIME_LOCKFREELOGGER

Function Documentation

__C__ SPHLFLogger_t SPHLFCircularLoggerCreate	(	block_size_t	buf_size,
		unsigned short	stride
	)

Allocate and initialize a shared storage block as a Lock Free Event Logger. Mark the logger as circular and specify a fixed Stride.

Allocate a block from SAS storage and initialize that block block as a Logger. The storage block must be power of two in size.

Parameters

buf_size	power of two size of the heap to be initialized.
stride	the stride offset is bytes between allocated entries.

Returns: a handle to the initialized SPHLFLogger_t.

__C__ void* SPHLFLoggerAllocRaw	(	SPHLFLogger_t	log,
		block_size_t	alloc_size
	)

Return the address of a (raw) Logger entry allocated from the specified logger.

The allocation size is rounded up to the next quadword boundary. Mostly for internal use and testing. If the specified logger is full the allocation may fail.

Parameters

log	Handle to a Logger.
alloc_size	size in bytes of the entry to be allocated.

Returns: the address of the raw Log Entry is returned if successful, or NULL if unsuccessful. For example the Allocate may fail if the logger is full.

__C__ SPHLFLoggerHandle_t* SPHLFLoggerAllocStrideTimeStamped	(	SPHLFLogger_t	log,
		int	catcode,
		int	subcode,
		SPHLFLoggerHandle_t *	handlespace
	)

Allocate and initialize the header, of a timestamped logger entry, from the specified logger.

The allocation size fixed as specified by the SPHLFCircularLoggerCreate. The Category, Subcategory, PID, TID and high persision timestamp are stored in the header of the new entry. Returns an entry handle which allows the application to insert application specific data into the entry via the sphlflogentry.h API. If the specified logger is full the allocation may fail.

Parameters

log	Handle to a Logger.
catcode	Category code to the new entry.
subcode	subcategory code to the new entry.
handlespace	Address of local area that will be initialied as a SPHLFLoggerHandle_t for the allocated entry.

Returns: Handle of the initialized logger entry, from the handlespace parm, or 0 (NULL) if the allocatation failed. For example the Allocate may fail if the logger is full and is not mark circular.

__C__ SPHLFLoggerHandle_t* SPHLFLoggerAllocStrideTimeStampedNoLock	(	SPHLFLogger_t	log,
		int	catcode,
		int	subcode,
		SPHLFLoggerHandle_t *	handlespace
	)

Allocate and initialize the header, of a timestamped logger entry, from the specified logger, without locking or memory barriers.

The allocation size fixed as specified by the SPHLFCircularLoggerCreate. The Category, Subcategory, PID, TID and high persision timestamp are stored in the header of the new entry. Returns an entry handle which allows the application to insert application specific data into the entry via the sphlflogentry.h API. If the specified logger is full the allocation may fail.

Warning: The NoLock form is only appropriate for single thread applications where the logger is not shared with other processes. Or if used in a multi-threaded application each thread should have it's own private logger instance.

Note: Also recommended that the NoLock allocates should be completed with SPHLFLogEntryWeakComplete() from sphlflogentry.h.

Parameters

log	Handle to a Logger.
catcode	Category code to the new entry.
subcode	subcategory code to the new entry.
handlespace	Address of local area that will be initialied as a SPHLFLoggerHandle_t for the allocated entry.

Returns: Handle of the initialized logger entry, from the handlespace parm, or 0 (NULL) if the allocatation failed. For example the Allocate may fail if the logger is full and is not mark circular.

__C__ SPHLFLoggerHandle_t* SPHLFLoggerAllocTimeStamped	(	SPHLFLogger_t	log,
		int	catcode,
		int	subcode,
		block_size_t	alloc_size,
		SPHLFLoggerHandle_t *	handlespace
	)

Allocate and initialize the header, of a timestamped logger entry, from the specified logger.

The allocation size is rounded up to the next quadword boundary and does not include the implicit size of the Timestamp entry header. The Category, Subcategory, PID, TID and high persision timestamp are stored in the header of the new entry. Returns an entry handle which allows the application to insert application specific data into the entry via the sphlflogentry.h API. If the specified logger is full the allocation may fail.

Parameters

log	Handle to a Logger.
catcode	Category code to the new entry.
subcode	subcategory code to the new entry.
alloc_size	Size in bytes of the entry to be allocated. The actual entry will be +16 bytes to include the entry header.
handlespace	Address of local area that will be initialied as a SPHLFLoggerHandle_t for the allocated entry.

Returns: Handle of the initialized logger entry handle, from the handlespace parm, or 0 (NULL) if the allocatation failed. For example the Allocate may fail if the logger is full.

__C__ SPHLFLoggerHandle_t* SPHLFLoggerAllocTimeStampedNoLock	(	SPHLFLogger_t	log,
		int	catcode,
		int	subcode,
		block_size_t	alloc_size,
		SPHLFLoggerHandle_t *	handlespace
	)

Allocate and initialize the header of a timestamped logger entry from the specified logger, without locking or memory barriers.

The allocation size is rounded up to the next quadword boundary and does not include the implicit size of the Timestamp entry header. The Category, Subcategory, PID, TID and high persision timestamp are stored in the header of the new entry. Returns an entry handle which allows the application to insert application specific data into the entry via the sphlflogentry.h API. If the specified logger is full the allocation may fail.

Warning: The NoLock form is only appropriate for single thread applications where the logger is not shared with other processes. Or if used in a multi-threaded application each thread should have it's own private logger instance.

Note: Also recommended that the NoLock allocates should be completed with SPHLFLogEntryWeakComplete() from sphlflogentry.h.

Parameters

log	Handle to a Logger.
catcode	Category code to the new entry.
subcode	subcategory code to the new entry.
alloc_size	Size in bytes of the entry to be allocated. The actual entry will be +16 bytes to include the entry header.
handlespace	Address of local area that will be initialied as a SPHLFLoggerHandle_t for the allocated entry.

Returns: Handle of the initialized logger entry handle, from the handlespace parm, or 0 (NULL) if the allocatation failed. For example the Allocate may fail if the logger is full.

__C__ SPHLFLogger_t SPHLFLoggerCreate ( block_size_t buf_size )

Allocate and initialize a shared storage block as a Lock Free Event Logger.

Allocate a block from SAS storage and initialize that block block as a Logger. The storage block must be power of two in size.

Parameters

buf_size power of two size of the heap to be initialized.

Returns: a handle to the initialized SPHLFLogger_t.

__C__ SPHLFLogIterator_t* SPHLFLoggerCreateIterator	(	SPHLFLogger_t	log,
		SPHLFLogIterator_t *	iteratorSpace
	)

Creates a logger Iterator for reading sequential entries from a specific logger.

Parameters

log	Handle to a Logger.
iteratorSpace	Address of local area that will be initialied as a SPHLFLogIterator_t associated with the log.

Returns: a pointer to the iterator space provided, initialized as a Logger Iterator if successful. Otherwise NULL.

__C__ int SPHLFLoggerDestroy ( SPHLFLogger_t log )

Destroys the logger and frees the SAS storage for reuse.

Parameters

log	Handle to a Logger to be destroyed.

Returns: 0 if successful.

__C__ int SPHLFLoggerEmpty ( SPHLFLogger_t log )

Return the status of the specified logger.

Parameters

log	Handle to a Logger.

Returns: true if the logger is currently Empty (no entries). Otherwise False.

__C__ int SPHLFLoggerEntryComplete ( SPHLFLoggerHandle_t * entryhandle )

Marks the entry specified by the entry handle as complete.

Also executes any memory barriers required by the platform to ensure that all previous stores to this entry by this thread are visible to other threads.

Parameters

entryhandle log entry Handle for an allocated entry.

Returns: 0 if successful.

__C__ int SPHLFLoggerEntryIsComplete ( SPHLFLoggerHandle_t * entryhandle )

Return the status of the entry specified by the entry handle.

Parameters

entryhandle log entry Handle for an allocated entry.

Returns: true if the entry was complete (SPHLFLoggerEntryComplete has been called fo this entry). Otherwise False.

__C__ int SPHLFLoggerEntryIsTimestamped ( SPHLFLoggerHandle_t * entryhandle )

Return the status of the entry specified by the entry handle.

Parameters

entryhandle log entry Handle for an allocated entry.

Returns: true if the entry was timestamped, otherwise False.

__C__ block_size_t SPHLFLoggerFreeSpace ( SPHLFLogger_t log )

Returns the amount of free space (in bytes) remaining in the specified logger.

Parameters

log	Handle to a Logger.

Returns: number of bytes of free space remainign in the Logger buffer.

__C__ int SPHLFLoggerFull ( SPHLFLogger_t log )

Return the status of the specified logger.

Parameters

log	Handle to a Logger.

Returns: true if the logger is currently full. Otherwise False.

__C__ SPHLFLogger_t SPHLFLoggerInit	(	void *	buf_seg,
		block_size_t	buf_size
	)

Initialize a shared storage block as a Lock Free Event Logger.

Initialize the specified storage block as Lock Free Logger control blocks. The storage block must be power of two in size and have the same power of two (or better) alignment. The type should be SAS_RUNTIME_LOCKFREELOGGER.

Parameters

buf_seg	a block of allocated SAS storage matching the buf_size.
buf_size	power of two size of the heap to be initialized.

Returns: a handle to the initialized SPHLFLogger_t.

__C__ SPHLFLogger_t SPHLFLoggerInitWithStride	(	void *	buf_seg,
		block_size_t	buf_size,
		unsigned short	entry_stride,
		unsigned int	options
	)

Initialize a shared storage block as a Lock Free Event Logger with a fixed entry stride.

Initialize the specified storage block as Lock Free Logger control blocks. The stride and control flags are also stored. The storage block must be power of two in size and have the same power of two (or better) alignment. The type should be SAS_RUNTIME_LOCKFREELOGGER.

Parameters

buf_seg	a block of allocated SAS storage matching the buf_size.
buf_size	power of two size of the heap to be initialized.
entry_stride	the stride offset is bytes between allocated entries.
options	option bits.

Returns: a handle to the initialized SPHLFLogger_t.

__C__ SPHLFLoggerHandle_t* SPHLFLoggerIteratorNext	(	SPHLFLogIterator_t *	iterator,
		SPHLFLoggerHandle_t *	handlespace
	)

For the provided Logger Iterator creates a entry handle for the next sequential Logger entry. The resulting entry handle can be used to read the contents of the Logger entry.

Parameters

iterator	Handle associated with a Logger.
handlespace	Address of local area that will be initialied as a SPHLFLoggerHandle_t for the allocated entry.

Returns: a pointer to the handle space provided, initialized as a Logger entry handle for the next sequential entry if successful. Otherwise NULL.

__C__ int SPHLFLoggerPrefetch ( SPHLFLogger_t log )

Prefetch pages from the specific logger.

Parameters

log	Handle to a Logger.

Returns: 0 if successful.

__C__ int SPHLFLoggerResetAsync ( SPHLFLogger_t log )

Resets the specific logger to empty state asynchronously (without locking or atomic updates).

Internal use for testing.

Parameters

log	Handle to a Logger.

Returns: 0 if successful.

__C__ int SPHLFLoggerResetIfFullSync ( SPHLFLogger_t log )

Resets the specific logger to empty state synchronously if it is currently full.

Internal use for testing.

Parameters

log	Handle to a Logger.

Returns: 0 if the logger was full and this thread did the reset. Otherwise 1 if not full or another thread already reset this logger. Other values indicated a serious error, for example the reference is not a logger.

__C__ int SPHLFLoggerSetCachePrefetch	(	SPHLFLogger_t	log,
		int	prefetch
	)

Set the cache-line prefetch options for entry allocate.

prefetch == 0; No prefetch issued.
prefetch == 1; Prefetch the currently allocated cache-line.
prefetch == 2; Prefetch the cache-line following the allocated entry.
prefetch == 3; Prefetch the current and next cache-lines.

@param log Handle to a Logger.
@param prefetch prefetch option code.
@return 0 if successful.

__C__ int SPHLFLoggerWrapped ( SPHLFLogger_t log )

Return the status of the specified logger.

Parameters

log	Handle to a Logger.

Returns: true if the logger is circular and has wrapped (at least once). Otherwise False.

Classes

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation