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"

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_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. More...

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

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

__C__ SPHLFLoggerHandle_t *	SPHLFPortalIteratorNext (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:

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.
Passing Logger event allocation requests through to the current Logger.
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

portal	Handle to a Log Portal.
iteratorSpace	Address 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

iterator	Handle associated with a Log Portal.
handlespace	Address 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

portal	Handle to a Log Portal.
log	Handle 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

portal	Handle to a Log Portal.
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.

__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

portal	Handle to a Log Portal.
catcode	Category code for the new entry.
subcode	subcategory code for the new entry.
handlespace	Address 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

portal	Handle to a Log Portal.
catcode	Category code for the new entry.
subcode	subcategory code for 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: 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

portal Handle 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_size power 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

portal Handle 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

portal Handle 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

portal Handle 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

portal Handle 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

portal Handle 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

portal	Handle to a Log Portal.
index	index 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_seg	a block of allocated SAS storage matching the buf_size.
buf_size	power of two size of the portal to be initialized.

Returns: a handle to the initialized SPHLFLogger_t.

Classes

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation