Shared Persistent Heap Data Environment Manual  1.1.0
Classes | Macros | Typedefs | Functions
sphlogportal.h File Reference

Shared Persistent Heap, log Portal. For shared memory multi-thread/multi-core applications. This implementation uses atomic operations to collect a set of Lock Free Loggers (SPHLFLogger_t) and control the switching to a fresh logger when it fills up, in a non-blocking but thread safe manner. More...

#include "sastype.h"
#include "sphlflogger.h"

Go to the source code of this file.

Classes

struct  SPHLFPortalIterator_t
 Instance of a Log Portal Iterator. More...
 

Typedefs

typedef void * SPHLogPortal_t
 Handle to an instance of SPH Log Portal. More...
 

Functions

__C__ SPHLogPortal_t SPHLogPortalInit (void *buf_seg, block_size_t buf_size)
 Initialize a shared storage block as a Log Portal. More...
 
__C__ SPHLogPortal_t SPHLogPortalCreate (block_size_t buf_size)
 Allocate and initialize a shared storage block as a Log Portal. More...
 
__C__ int SPHLogPortalEmpty (SPHLogPortal_t portal)
 Return the status of the specified Log Portal. More...
 
__C__ int SPHLogPortalEntries (SPHLogPortal_t portal)
 Return the number of active Loggers in the portal list. More...
 
__C__ int SPHLogPortalCapacity (SPHLogPortal_t portal)
 Return the maximum number of Loggers the list can hold. More...
 
__C__ SPHLFLogger_t SPHLogPortalAddLogger (SPHLogPortal_t portal, SPHLFLogger_t log)
 Insert a SPHLFLogger_t into the next free slot og this Log Portal. This Logger can be then be used to log events via the Log Portal (when it becomes the current logger). Use the SPHLogPortalAlloc* functions to allocate and complete log entries. More...
 
__C__ SPHLFLogger_t SPHLogPortalGetCurrentLogger (SPHLogPortal_t portal)
 Return the handle of the current Logger target of the Portal. More...
 
__C__ SPHLFLogger_t SPHLogPortalGetLoggerByIndex (SPHLogPortal_t portal, longPtr_t index)
 Return the handle of the Logger in the Portal list slot specified by the index number. More...
 
__C__ int SPHLogPortalGetCurrentIndex (SPHLogPortal_t portal)
 Return the index of the current Logger target of the Portal. More...
 
__C__ SPHLFLoggerHandle_tSPHLogPortalAllocStrideTimeStamped (SPHLogPortal_t portal, int catcode, int subcode, SPHLFLoggerHandle_t *handlespace)
 Return the handle of a Logger entry allocated from the current logger of the Portal. If the current logger is full, attempt to move current to the next available Logger and retry. More...
 
__C__ SPHLFLoggerHandle_tSPHLogPortalAllocTimeStamped (SPHLogPortal_t portal, int catcode, int subcode, block_size_t alloc_size, SPHLFLoggerHandle_t *handlespace)
 Return the handle of a Logger entry allocated from the current logger of the Portal. If the current logger is full, attempt to move current to the next available Logger and retry. More...
 
__C__ SPHLFPortalIterator_tSPHLFPortalCreateIterator (SPHLogPortal_t portal, SPHLFPortalIterator_t *iteratorSpace)
 Create an iterator positioned at the first entry of the first logger attached to this portal. More...
 
__C__ SPHLFLoggerHandle_tSPHLFPortalIteratorNext (SPHLFPortalIterator_t *iterator, SPHLFLoggerHandle_t *handlespace)
 Access a sequence of completed logger entries in-order. More...
 
__C__ void * SPHLogPortalAllocRaw (SPHLogPortal_t portal, block_size_t alloc_size)
 Return the address of a (raw) Logger entry allocated from the current logger. More...
 
__C__ int SPHLogPortalDestroy (SPHLogPortal_t portal)
 Destroy the Log Portal and free the storage. More...
 

Detailed Description

Shared Persistent Heap, log Portal. For shared memory multi-thread/multi-core applications. This implementation uses atomic operations to collect a set of Lock Free Loggers (SPHLFLogger_t) and control the switching to a fresh logger when it fills up, in a non-blocking but thread safe manner.

! A Log Portal manages a set of Lock Free Loggers. This includes:

  1. Managing a list of Logger spaces available for logging events.
    • Allocating the next free slot for adding a logger to the list.
    • Managing the current Logger within the list.
    • Control access to the Logger list elements.
  2. Passing Logger event allocation requests through to the current Logger.
  3. Advancing the Current logger to next free Logger when the current Logger fills up.

A portal is used when the required capacity for logger entries exceeds that posible for a single logger. Or we need to support rolling/continuous logs over a long period of time. By switching out filled loggers with new/empty loggers, logging can continue indeffinitely.

Typedef Documentation

typedef void* SPHLogPortal_t

Handle to an instance of SPH Log Portal.

The type is SAS_RUNTIME_LOGPORTAL

Function Documentation

__C__ SPHLFPortalIterator_t* SPHLFPortalCreateIterator ( SPHLogPortal_t  portal,
SPHLFPortalIterator_t iteratorSpace 
)

Create an iterator positioned at the first entry of the first logger attached to this portal.

Returns the handle of a Portal Iterator. The iterator can be used to iterate through the completed entries of the attached loggers. Starting with the initial logger and continuing in sequence through any additional loggers that are non-empty.

Parameters
portalHandle to a Log Portal.
iteratorSpaceAddress of local area that will be initialied as a SPHLFLogIterator_t associated with the log.
Returns
the address of the provided Iterator_space or NULL. If successful, The address of Iterator_space initialized as a SPHLFPortalIterator_t is returned. Otherwise NULL is returned (for example if the Portal was empty).
__C__ SPHLFLoggerHandle_t* SPHLFPortalIteratorNext ( SPHLFPortalIterator_t iterator,
SPHLFLoggerHandle_t handlespace 
)

Access a sequence of completed logger entries in-order.

Returns the handle of the current logger entry for the current logger for the provided Portal Iterator. The logger entry handle can of then be used to access the contents of the logger entry. The iterator is advanced to the next logger entry. If the iterator is positioned at the end of the current logger then the iterator will be advanced to the first entry of the next logger allocated to this portal. If we are at the end of the list of allocated loggers we are done.

Parameters
iteratorHandle associated with a Log Portal.
handlespaceAddress of local area that will be initialied as a SPHLFLoggerHandle_t for the allocated entry.
Returns
the address of the provided handlespace or NULL. If successful, The address of handlespace initialized as a SPHLFLoggerHandle_t is returned. Otherwise NULL is returned (for example if the Portal was empty or we are at the end of the last logger).
__C__ SPHLFLogger_t SPHLogPortalAddLogger ( SPHLogPortal_t  portal,
SPHLFLogger_t  log 
)

Insert a SPHLFLogger_t into the next free slot og this Log Portal. This Logger can be then be used to log events via the Log Portal (when it becomes the current logger). Use the SPHLogPortalAlloc* functions to allocate and complete log entries.

Parameters
portalHandle to a Log Portal.
logHandle to a Lock Free Logger to be inserted.
Returns
The provided SPHLFLogger_t handle or NULL. If successful, the provided Logger handle is returned. Otherwise NULL (For example the Add may fail if the Logger list is already at capacity.)
__C__ void* SPHLogPortalAllocRaw ( SPHLogPortal_t  portal,
block_size_t  alloc_size 
)

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

The allocation size is rounded up to the next quadword boundary. Mostly for internal use and testing. If the specified portal's loggers are full the allocation may fail.

Parameters
portalHandle to a Log Portal.
alloc_sizesize in bytes of the entry to be allocated.
Returns
the address of the raw Log Entry is returned if successful, or NULL if unsuccessful.
__C__ SPHLFLoggerHandle_t* SPHLogPortalAllocStrideTimeStamped ( SPHLogPortal_t  portal,
int  catcode,
int  subcode,
SPHLFLoggerHandle_t handlespace 
)

Return the handle of a Logger entry allocated from the current logger of the Portal. If the current logger is full, attempt to move current to the next available Logger and retry.

Parameters
portalHandle to a Log Portal.
catcodeCategory code for the new entry.
subcodesubcategory code for the new entry.
handlespaceAddress of local area that will be initialied as a SPHLFLoggerHandle_t for the allocated entry.
Returns
address of handleorg or NULL, The address of the initialized Log Entry Handle is returned if successful, or NULL if unsuccessful (for example the Allocate may fail if the last Logger in the list is full).
__C__ SPHLFLoggerHandle_t* SPHLogPortalAllocTimeStamped ( SPHLogPortal_t  portal,
int  catcode,
int  subcode,
block_size_t  alloc_size,
SPHLFLoggerHandle_t handlespace 
)

Return the handle of a Logger entry allocated from the current logger of the Portal. If the current logger is full, attempt to move current to the next available Logger and retry.

Parameters
portalHandle to a Log Portal.
catcodeCategory code for the new entry.
subcodesubcategory code for the new entry.
alloc_sizeSize in bytes of the entry to be allocated. The actual entry will be +16 bytes to include the entry header.
handlespaceAddress of local area that will be initialied as a SPHLFLoggerHandle_t for the allocated entry.
Returns
address of handleorg or NULL, The address of the initialized Log Entry Handle is returned if successful, or NULL if unsuccessful (for example the allocate may fail if the last Logger in the list is full).
__C__ int SPHLogPortalCapacity ( SPHLogPortal_t  portal)

Return the maximum number of Loggers the list can hold.

Parameters
portalHandle to a Log Portal.
Returns
maximum number of Logger entries for this portal.
__C__ SPHLogPortal_t SPHLogPortalCreate ( block_size_t  buf_size)

Allocate and initialize a shared storage block as a Log Portal.

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

Parameters
buf_sizepower of two size of the portal to be created.
Returns
a handle to the initialized SPHLFLogger_t.
__C__ int SPHLogPortalDestroy ( SPHLogPortal_t  portal)

Destroy the Log Portal and free the storage.

NOTE need to add code to free any attached Loggers

Parameters
portalHandle to a Logger to be destroyed.
Returns
0 if successful.
__C__ int SPHLogPortalEmpty ( SPHLogPortal_t  portal)

Return the status of the specified Log Portal.

Parameters
portalHandle to a Log Portal.
Returns
true if the portal is currently Empty (no entries). Otherwise False.
__C__ int SPHLogPortalEntries ( SPHLogPortal_t  portal)

Return the number of active Loggers in the portal list.

Parameters
portalHandle to a Log Portal.
Returns
current number of Logger entries for this portal.
__C__ int SPHLogPortalGetCurrentIndex ( SPHLogPortal_t  portal)

Return the index of the current Logger target of the Portal.

Parameters
portalHandle to a Log Portal.
Returns
Non-negative int or -1, The current Logger index is returned if successful, or -1 if unsuccessful. For example the Get may fail if the Logger list is currently empty.
__C__ SPHLFLogger_t SPHLogPortalGetCurrentLogger ( SPHLogPortal_t  portal)

Return the handle of the current Logger target of the Portal.

Parameters
portalHandle to a Log Portal.
Returns
SPHLFLogger_t or NULL, The Logger handle is returned if successful, or NULL if unsuccessful. For example the Get may fail if the Logger list is currently empty or the last available Logger is already full.
__C__ SPHLFLogger_t SPHLogPortalGetLoggerByIndex ( SPHLogPortal_t  portal,
longPtr_t  index 
)

Return the handle of the Logger in the Portal list slot specified by the index number.

Parameters
portalHandle to a Log Portal.
indexindex of the logger to be returned.
Returns
SPHLFLogger_t or NULL, The Logger address is returned if successful, or NULL if unsuccessful. For example the Get may fail if the Logger list is currently empty or the index is out of range.
__C__ SPHLogPortal_t SPHLogPortalInit ( void *  buf_seg,
block_size_t  buf_size 
)

Initialize a shared storage block as a Log Portal.

Initialize the control blocks within the specified storage block as a Log Portal. The storage block must be power of two in size and have the same power of two (or better) alignment. The type will be SAS_RUNTIME_LOGPORTAL.

Parameters
buf_sega block of allocated SAS storage matching the buf_size.
buf_sizepower of two size of the portal to be initialized.
Returns
a handle to the initialized SPHLFLogger_t.