sphlflogger.h File Reference

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"`

Go to the source code of this file.

## 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)
}
}
SASJoinRegion
__C__ int SASJoinRegion()
Join this process to a SAS Region.
SPHContextAddName
__C__ int SPHContextAddName(SPHContext_t contxt, char *name, void *value)
Add a name/address mapping to this context.
SPHSetupProjectContext
__C__ SPHContext_t SPHSetupProjectContext(char *project_name)
Setup the root and named project contexts. A project context is just a second level context named in ...
SPHContext_t
void * SPHContext_t
Handle to an instance of SPH Context.
Definition: sphcontext.h:48
SPHLFLogger_t
void * SPHLFLogger_t
Handle to an instance of SPH Lock Free Logger.
Definition: sphlflogger.h:173
SPHLFCircularLoggerCreate
__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 circul...

    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);
...
}
}
getProjectContextByName
__C__ SPHContext_t getProjectContextByName(char *project_name)
return the address of the named project context.
SPHContextFindByName
__C__ void * SPHContextFindByName(SPHContext_t contxt, char *name)
Find the address value associated with a name within a specific context.
SPHLFLoggerAllocStrideTimeStamped
__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.
SPHLFLoggerHandle_t
Instance of a Lock Free Logger Entry Handle.
Definition: sphlflogger.h:244

    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);
}
SPHLFLogEntryComplete
static int SPHLFLogEntryComplete(SPHLFLoggerHandle_t *handlespace)
Marks the entry specified by the entry handle as complete. Also executes write memory barries require...
Definition: sphlflogentry.h:111

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);
}
}
SPHLFLogEntryTimeStamp
static sphtimer_t SPHLFLogEntryTimeStamp(SPHLFLoggerHandle_t *handlespace)
Return the time stamp value for the entry specified by the entry handle.
Definition: sphlflogentry.h:160
SPHLFLogEntryTID
static sphpid16_t SPHLFLogEntryTID(SPHLFLoggerHandle_t *handlespace)
Return the thread ID for the entry specified by the entry handle.
Definition: sphlflogentry.h:198
SPHLFLogEntrySubcat
static int SPHLFLogEntrySubcat(SPHLFLoggerHandle_t *handlespace)
Return the entry sub-category for the entry specified by the entry handle.
Definition: sphlflogentry.h:255
SPHLFLogEntryCategory
static int SPHLFLogEntryCategory(SPHLFLoggerHandle_t *handlespace)
Return the entry category for the entry specified by the entry handle.
Definition: sphlflogentry.h:234
SPHLFLogEntryPID
static sphpid16_t SPHLFLogEntryPID(SPHLFLoggerHandle_t *handlespace)
Return the process ID for the entry specified by the entry handle.
Definition: sphlflogentry.h:179
SPHLFLoggerIteratorNext
__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....
SPHLFLoggerCreateIterator
__C__ SPHLFLogIterator_t * SPHLFLoggerCreateIterator(SPHLFLogger_t log, SPHLFLogIterator_t *iteratorSpace)
Creates a logger Iterator for reading sequential entries from a specific logger.
sphtimer_t
unsigned long long int sphtimer_t
Value from TB/TSC register (64-bits on all platforms).
Definition: sphtimer.h:66
SPHLFLogIterator_t
Instance of a Lock Free Logger Iterator.
Definition: sphlflogger.h:264

## Macro Definition Documentation

## SPHLFLOGGER_CIRCULAR_RESETMASK

#define SPHLFLOGGER_CIRCULAR_RESETMASK

Value:
(SPHLFLOGGER_CIRCULAR | \
SPHLFLOGGER_CACHE_PREFETCH0 | \
SPHLFLOGGER_CACHE_PREFETCH1)
SPHLFLOGGER_CIRCULAR
#define SPHLFLOGGER_CIRCULAR
internal options flag for circular log buffers
Definition: sphlflogger.h:280

internal options mask flag used the reset circular log buffers

## Typedef Documentation

## SPHLFLogger_t

typedef void* SPHLFLogger_t

Handle to an instance of SPH Lock Free Logger.

    The type is SAS_RUNTIME_LOCKFREELOGGER

## Function Documentation

## SPHLFCircularLoggerCreate()

__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.

## SPHLFLoggerAllocRaw()

__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.

    @param log Handle to a Logger.
    @param alloc_size size in bytes of the entry to be allocated.
    @return 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.

## SPHLFLoggerAllocStrideTimeStamped()

__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.

## SPHLFLoggerAllocStrideTimeStampedNoLock()

__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.

## SPHLFLoggerAllocTimeStamped()

__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.

## SPHLFLoggerAllocTimeStampedNoLock()

__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.

## SPHLFLoggerCreate()

__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.

## SPHLFLoggerCreateIterator()

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

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

    @param log Handle to a Logger.
    @param iteratorSpace Address of local area that will be initialied as a
    SPHLFLogIterator_t associated with the log.
    @return a pointer to the iterator space provided,
    initialized as a Logger Iterator if successful.
    Otherwise NULL.

## SPHLFLoggerDestroy()

__C__ int SPHLFLoggerDestroy | ( | SPHLFLogger_t | log | ) |

Destroys the logger and frees the SAS storage for reuse.

    @param log Handle to a Logger to be destroyed.
    @return 0 if successful.

## SPHLFLoggerEmpty()

__C__ int SPHLFLoggerEmpty | ( | SPHLFLogger_t | log | ) |

Return the status of the specified logger.

    @param log Handle to a Logger.
    @return true if the logger is currently Empty (no entries).
    Otherwise False.

## SPHLFLoggerEntryComplete()

__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.

    @param entryhandle log entry Handle for an allocated entry.
    @return 0 if successful.

## SPHLFLoggerEntryIsComplete()

__C__ int SPHLFLoggerEntryIsComplete | ( | SPHLFLoggerHandle_t * | entryhandle | ) |

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

    @param entryhandle log entry Handle for an allocated entry.
    @return true if the entry was complete (SPHLFLoggerEntryComplete
    has been called fo this entry). Otherwise False.

## SPHLFLoggerEntryIsTimestamped()

__C__ int SPHLFLoggerEntryIsTimestamped | ( | SPHLFLoggerHandle_t * | entryhandle | ) |

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

    @param entryhandle log entry Handle for an allocated entry.
    @return true if the entry was timestamped, otherwise False.

## SPHLFLoggerFreeSpace()

__C__ block_size_t SPHLFLoggerFreeSpace | ( | SPHLFLogger_t | log | ) |

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

    @param log Handle to a Logger.
    @return number of bytes of free space remainign in the Logger buffer.

## SPHLFLoggerFull()

__C__ int SPHLFLoggerFull | ( | SPHLFLogger_t | log | ) |

Return the status of the specified logger.

    @param log Handle to a Logger.
    @return true if the logger is currently full.
    Otherwise False.

## SPHLFLoggerInit()

__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.

    @param buf_seg a block of allocated SAS storage matching the buf_size.
    @param buf_size power of two size of the heap to be initialized.
    @return a handle to the initialized SPHLFLogger_t.

## SPHLFLoggerInitWithStride()

__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.

## SPHLFLoggerIteratorNext()

__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.

## SPHLFLoggerPrefetch()

__C__ int SPHLFLoggerPrefetch | ( | SPHLFLogger_t | log | ) |

Prefetch pages from the specific logger.

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

## SPHLFLoggerResetAsync()

__C__ int SPHLFLoggerResetAsync | ( | SPHLFLogger_t | log | ) |

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

    Internal use for testing.

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

## SPHLFLoggerResetIfFullSync()

__C__ int SPHLFLoggerResetIfFullSync | ( | SPHLFLogger_t | log | ) |

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

    Internal use for testing.

    @param log Handle to a Logger.
    @return 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.

## SPHLFLoggerSetCachePrefetch()

__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.

## SPHLFLoggerWrapped()

__C__ int SPHLFLoggerWrapped | ( | SPHLFLogger_t | log | ) |

Return the status of the specified logger.

    @param log Handle to a Logger.
    @return true if the logger is circular and has wrapped (at least once).
    Otherwise False.