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_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:

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

## SPHLogPortal_t

typedef void* SPHLogPortal_t

Handle to an instance of SPH Log Portal.

    The type is SAS_RUNTIME_LOGPORTAL

## Function Documentation

## SPHLFPortalCreateIterator()

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

## SPHLFPortalIteratorNext()

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

    @param iterator Handle associated with a Log Portal.
    @param handlespace Address of local area that will be initialied as a
    SPHLFLoggerHandle_t for the allocated entry.
    @return 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).

## SPHLogPortalAddLogger()

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

## SPHLogPortalAllocRaw()

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

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

## SPHLogPortalAllocStrideTimeStamped()

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

## SPHLogPortalAllocTimeStamped()

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

## SPHLogPortalCapacity()

__C__ int SPHLogPortalCapacity | ( | SPHLogPortal_t | portal | ) |

Return the maximum number of Loggers the list can hold.

    @param portal Handle to a Log Portal.
    @return maximum number of Logger entries for this portal.

## SPHLogPortalCreate()

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

    @param buf_size power of two size of the portal to be created.
    @return a handle to the initialized SPHLFLogger_t.

## SPHLogPortalDestroy()

__C__ int SPHLogPortalDestroy | ( | SPHLogPortal_t | portal | ) |

Destroy the Log Portal and free the storage.

    NOTE need to add code to free any attached Loggers

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

## SPHLogPortalEmpty()

__C__ int SPHLogPortalEmpty | ( | SPHLogPortal_t | portal | ) |

Return the status of the specified Log Portal.

    @param portal Handle to a Log Portal.
    @return true if the portal is currently Empty (no entries).
    Otherwise False.

## SPHLogPortalEntries()

__C__ int SPHLogPortalEntries | ( | SPHLogPortal_t | portal | ) |

Return the number of active Loggers in the portal list.

    @param portal Handle to a Log Portal.
    @return current number of Logger entries for this portal.

## SPHLogPortalGetCurrentIndex()

__C__ int SPHLogPortalGetCurrentIndex | ( | SPHLogPortal_t | portal | ) |

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

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

## SPHLogPortalGetCurrentLogger()

__C__ SPHLFLogger_t SPHLogPortalGetCurrentLogger | ( | SPHLogPortal_t | portal | ) |

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

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

## SPHLogPortalGetLoggerByIndex()

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

## SPHLogPortalInit()

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

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