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

Shared Persistent Heap, logger/queue etc event entry status, update, and access functions. More...

#include <string.h>
#include "sastype.h"
#include "sasatom.h"
#include "sphtimer.h"

Go to the source code of this file.

Classes

struct  sphLFEntryLayout_t
 Fields defining the entry header details word. More...
 
union  sphLFEntry_t
 Union of Entry details with 32-bit word for atomic update. More...
 
struct  SPHLFEntryHeader_t
 Instance of a Lock Free Entry Header. More...
 
struct  SPHLFEntryHandle_t
 Instance of a Lock Free event data Entry Handle. More...
 

Macros

#define SPHENTRYGETSTRUCTPTR(__handle, __struct)   SPHLFEntryGetStructPtr(__handle, sizeof(__struct), __alignof__(__struct))
 Macro for using sizeof/__alignof__ parms with SPHLFEntryGetStructPtr function.
 
#define SPHENTRYALLOCSTRUCT(__handle, __struct)   SPHLFEntryAllocStruct(__handle, sizeof(__struct), __alignof__(__struct))
 Macro for using sizeof/__alignof__ parms with SPHLFEntryAllocStruct function.
 

Typedefs

typedef unsigned long longPtr_t
 unsigned int type, consistent with the size of a pointer and used for pointer calculations
 
typedef unsigned int sphLFEntryID_t
 Aggregate type for handling sphLogEntryLayout_t.
 
typedef unsigned short sphpid16_t
 Common type for PID/TID values stored in event entries.
 

Functions

int SPHLFEntryStrongComplete (SPHLFEntryHandle_t *handlespace)
 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. More...
 
int SPHLFEntryWeakComplete (SPHLFEntryHandle_t *handlespace)
 Marks the entry specified by the entry handle as complete. No memory barriers are performance. On out-of-order machines there are no guarantee that all previous stores by this thread are visible to other threads. More...
 
int SPHLFEntryComplete (SPHLFEntryHandle_t *handlespace)
 Marks the entry specified by the entry handle as complete. Also executes write memory barries required by the platform to ensure that all previous stores by this thread to this entry are complete. More...
 
int SPHLFEntryIsComplete (SPHLFEntryHandle_t *handlespace)
 Return the status of the entry specified by the entry handle. More...
 
int SPHLFEntryIsTimestamped (SPHLFEntryHandle_t *handlespace)
 Return the status of the entry specified by the entry handle. More...
 
sphtimer_t SPHLFEntryTimeStamp (SPHLFEntryHandle_t *handlespace)
 Return the time stamp value for the entry specified by the entry handle. More...
 
sphpid16_t SPHLFEntryPID (SPHLFEntryHandle_t *handlespace)
 Return the process ID for the entry specified by the entry handle. More...
 
sphpid16_t SPHLFEntryTID (SPHLFEntryHandle_t *handlespace)
 Return the thread ID for the entry specified by the entry handle. More...
 
SPHLFEntryHeader_tSPHLFEntryHeader (SPHLFEntryHandle_t *handlespace)
 Return the address for the entry header specified by the entry handle. More...
 
int SPHLFEntryCategory (SPHLFEntryHandle_t *handlespace)
 Return the entry category for the entry specified by the entry handle. More...
 
int SPHLFEntrySubcat (SPHLFEntryHandle_t *handlespace)
 Return the entry sub-category for the entry specified by the entry handle. More...
 
void * SPHLFEntryGetFreePtr (SPHLFEntryHandle_t *handle)
 Return the first free byte address for the entry specified by the entry handle. More...
 
void * SPHLFEntryGetStructPtr (SPHLFEntryHandle_t *handle, unsigned long __size, unsigned long __align)
 Return the correctly aligned pointer for a struct or array starting at the next free location within the entry. More...
 
void * SPHLFEntryAllocStruct (SPHLFEntryHandle_t *handle, unsigned long __size, unsigned long __align)
 Allocate space for struct starting at the next free location within the entry. More...
 
int SPHLFEntryAddString (SPHLFEntryHandle_t *handle, char *value)
 Insert a C string at the next free location within the entry. More...
 
int SPHLFEntryAddChar (SPHLFEntryHandle_t *handle, char value)
 Insert a character at the next free location within the entry. More...
 
int SPHLFEntryAddShort (SPHLFEntryHandle_t *handle, short int value)
 Insert a short int at the next free location within the entry. More...
 
int SPHLFEntryAddInt (SPHLFEntryHandle_t *handle, int value)
 Insert a int at the next free location within the entry. More...
 
int SPHLFEntryAddLong (SPHLFEntryHandle_t *handle, long value)
 Insert a long int at the next free location within the entry. More...
 
int SPHLFEntryAddPtr (SPHLFEntryHandle_t *handle, void *value)
 Insert a void* at the next free location within the entry. More...
 
int SPHLFEntryAddLongLong (SPHLFEntryHandle_t *handle, long long value)
 Insert a long long int at the next free location within the entry. More...
 
int SPHLFEntryAddFloat (SPHLFEntryHandle_t *handle, float value)
 Insert a float at the next free location within the entry. More...
 
int SPHLFEntryAddDouble (SPHLFEntryHandle_t *handle, double value)
 Insert a double at the next free location within the entry. More...
 
char SPHLFEntryGetNextChar (SPHLFEntryHandle_t *handle)
 Return the next char from the entry via the current next value pointer. The internal next value pointer is advanced to the next location. More...
 
char * SPHLFEntryGetNextString (SPHLFEntryHandle_t *handle)
 Return the pointer to the next C string from the logger entry via the current next value pointer. The internal next value pointer is advanced to the next location after the string NUL char. More...
 
short int SPHLFEntryGetNextShort (SPHLFEntryHandle_t *handle)
 Return the next short int from the entry via the current next value pointer. Leading bytes may be skipped to get the required alignment. The internal next value pointer is advanced to the next location. More...
 
int SPHLFEntryGetNextInt (SPHLFEntryHandle_t *handle)
 Return the next int from the entry via the current next value pointer. Leading bytes may be skipped to get the required alignment. The internal next value pointer is advanced to the next location. More...
 
long SPHLFEntryGetNextLong (SPHLFEntryHandle_t *handle)
 Return the next long int from the entry via the current next value pointer. Leading bytes may be skipped to get the required alignment. The internal next value pointer is advanced to the next location. More...
 
void * SPHLFEntryGetNextPtr (SPHLFEntryHandle_t *handle)
 Return the next void* from the entry via the current next value pointer. Leading bytes may be skipped to get the required alignment. The internal next value pointer is advanced to the next location. More...
 
long long SPHLFEntryGetNextLongLong (SPHLFEntryHandle_t *handle)
 Return the next long long int from the entry via the current next value pointer. Leading bytes may be skipped to get the required alignment. The internal next value pointer is advanced to the next location. More...
 
float SPHLFEntryGetNextFloat (SPHLFEntryHandle_t *handle)
 Return the next float from the entry via the current next value pointer. Leading bytes may be skipped to get the required alignment. The internal next value pointer is advanced to the next location. More...
 
double SPHLFEntryGetNextDouble (SPHLFEntryHandle_t *handle)
 Return the next double from the entry via the current next value pointer. Leading bytes may be skipped to get the required alignment. The internal next value pointer is advanced to the next location. More...
 

Detailed Description

Shared Persistent Heap, logger/queue etc event entry status, update, and access functions.

Author
Steven Munroe - initial API and implementation
 For shared memory multi-thread/multi-core applications. Once the
 Logger or Queue functions have atomically allocated an entry,
 the "entry" APIs supports adding additional data to the entry and
 retrieving that date later.

 Supported functions include:
 storing category specific event data,
 atomic completion of an entry,
 Getting entry status (complete and timestamped)
 Getting entry header elements (timestamp, PID, TID, Category, and Sub-category),
 Retrieving category specific event data entries,
 and direct pointer access the header and data of the entry.

 This Entry access API supports read out of the 16 byte
 entry header including: Entry status and length.  Entry
 Category and SubCategory codes. Process and Thread Ids.  High
 resolution timestamp.

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

Function Documentation

int SPHLFEntryAddChar ( SPHLFEntryHandle_t handle,
char  value 
)
inline

Insert a character at the next free location within the entry.

Parameters
handleEntry Handle for an allocated entry.
valuea char value.
Returns
0 if successful, -1 if the insert fails. For example if remaining entry space is insufficient to hold a char.
int SPHLFEntryAddDouble ( SPHLFEntryHandle_t handle,
double  value 
)
inline

Insert a double at the next free location within the entry.

Parameters
handleEntry Handle for an allocated entry.
valuea double value.
Returns
0 if successful, -1 if the insert fails. For example if remaining entry space is insufficient to hold a double plus any required alignment.
int SPHLFEntryAddFloat ( SPHLFEntryHandle_t handle,
float  value 
)
inline

Insert a float at the next free location within the entry.

Parameters
handleEntry Handle for an allocated entry.
valuea float value.
Returns
0 if successful, -1 if the insert fails. For example if remaining entry space is insufficient to hold a float plus any required alignment.
int SPHLFEntryAddInt ( SPHLFEntryHandle_t handle,
int  value 
)
inline

Insert a int at the next free location within the entry.

Parameters
handleEntry Handle for an allocated entry.
valuea int value.
Returns
0 if successful, -1 if the insert fails. For example if remaining entry space is insufficient to hold a int plus any required alignment.
int SPHLFEntryAddLong ( SPHLFEntryHandle_t handle,
long  value 
)
inline

Insert a long int at the next free location within the entry.

Parameters
handleEntry Handle for an allocated entry.
valuea long int value.
Returns
0 if successful, -1 if the insert fails. For example if remaining entry space is insufficient to hold a long int plus any required alignment.
int SPHLFEntryAddLongLong ( SPHLFEntryHandle_t handle,
long long  value 
)
inline

Insert a long long int at the next free location within the entry.

Parameters
handleEntry Handle for an allocated entry.
valuea long long int value.
Returns
0 if successful, -1 if the insert fails. For example if remaining entry space is insufficient to hold a long long int plus any required alignment.
int SPHLFEntryAddPtr ( SPHLFEntryHandle_t handle,
void *  value 
)
inline

Insert a void* at the next free location within the entry.

Parameters
handleEntry Handle for an allocated entry.
valuea void* (C pointer) value.
Returns
0 if successful, -1 if the insert fails. For example if remaining entry space is insufficient to hold a void* plus any required alignment.
int SPHLFEntryAddShort ( SPHLFEntryHandle_t handle,
short int  value 
)
inline

Insert a short int at the next free location within the entry.

Parameters
handleEntry Handle for an allocated entry.
valuea short int value.
Returns
0 if successful, -1 if the insert fails. For example if remaining entry space is insufficient to hold a short int plus any required alignment.
int SPHLFEntryAddString ( SPHLFEntryHandle_t handle,
char *  value 
)
inline

Insert a C string at the next free location within the entry.

Parameters
handleEntry Handle for an allocated entry.
valuepointer to a C string value.
Returns
0 if successful, -1 if the insert fails. For example if the string is too large for the remain entry free space.
void* SPHLFEntryAllocStruct ( SPHLFEntryHandle_t handle,
unsigned long  __size,
unsigned long  __align 
)
inline

Allocate space for struct starting at the next free location within the entry.

Allocate space in the log entry for a multi-field structure or an array. The returned pointer can then be used to directly store data into struct fields or array entries. The SPHENTRYALLOCSTRUCT can be used to insure the correct usage sizeof and alignof to provide values for the __size and __align parameters.

Note
This function should be used instead of SPHLFEntryGetFreePtr if additional data may be added later to the same entry.
Parameters
handleEntry Handle for an allocated entry.
__sizeof the struct/array to allocate.
__alignalignment requirement of the struct/array space to allocated.
Returns
address of the allocated free space. NULL indicates failure. For example if remaining entry space is insufficient to hold the struct at the required alignment.
int SPHLFEntryCategory ( SPHLFEntryHandle_t handlespace)
inline

Return the entry category for the entry specified by the entry handle.

Parameters
handlespaceEntry Handle for an allocated entry.
Returns
the category from the entry, if the entry was valid. Otherwise return 0.
int SPHLFEntryComplete ( SPHLFEntryHandle_t handlespace)
inline

Marks the entry specified by the entry handle as complete. Also executes write memory barries required by the platform to ensure that all previous stores by this thread to this entry are complete.

Parameters
handlespaceEntry Handle for an allocated entry.
Returns
a 0 value indicates success.
void* SPHLFEntryGetFreePtr ( SPHLFEntryHandle_t handle)
inline

Return the first free byte address for the entry specified by the entry handle.

Warning
This function should be used carefully. It is not safe to use if other application functions may need to update the same entry. It is also not safe to use for software that needs to cross platform because it does not handle platform specific size and alignment requirements.
Note
The SPHLOGENTRYALLOCSTRUCT/SPHLFlogEntryAllocStruct API is recommended for code that needs to operate cross platform.
Parameters
handleEntry Handle for an allocated entry.
Returns
address the entries free space.
char SPHLFEntryGetNextChar ( SPHLFEntryHandle_t handle)
inline

Return the next char from the entry via the current next value pointer. The internal next value pointer is advanced to the next location.

Parameters
handleEntry Handle for an allocated entry.
Returns
the char value if successful, 0 (NUL) if the get fails. For example if the next is at the end of the Logger entry.
double SPHLFEntryGetNextDouble ( SPHLFEntryHandle_t handle)
inline

Return the next double from the entry via the current next value pointer. Leading bytes may be skipped to get the required alignment. The internal next value pointer is advanced to the next location.

Parameters
handleEntry Handle for an allocated entry.
Returns
the double value if successful, 0.0 if the get fails. For example if the next is at the end of the Logger entry.
float SPHLFEntryGetNextFloat ( SPHLFEntryHandle_t handle)
inline

Return the next float from the entry via the current next value pointer. Leading bytes may be skipped to get the required alignment. The internal next value pointer is advanced to the next location.

Parameters
handleEntry Handle for an allocated entry.
Returns
the float value if successful, 0.0 if the get fails. For example if the next is at the end of the Logger entry.
int SPHLFEntryGetNextInt ( SPHLFEntryHandle_t handle)
inline

Return the next int from the entry via the current next value pointer. Leading bytes may be skipped to get the required alignment. The internal next value pointer is advanced to the next location.

Parameters
handleEntry Handle for an allocated entry.
Returns
the int value if successful, 0 if the get fails. For example if the next is at the end of the Logger entry.
long SPHLFEntryGetNextLong ( SPHLFEntryHandle_t handle)
inline

Return the next long int from the entry via the current next value pointer. Leading bytes may be skipped to get the required alignment. The internal next value pointer is advanced to the next location.

Parameters
handleEntry Handle for an allocated entry.
Returns
the long int value if successful, 0 if the get fails. For example if the next is at the end of the Logger entry.
long long SPHLFEntryGetNextLongLong ( SPHLFEntryHandle_t handle)
inline

Return the next long long int from the entry via the current next value pointer. Leading bytes may be skipped to get the required alignment. The internal next value pointer is advanced to the next location.

Parameters
handleEntry Handle for an allocated entry.
Returns
the long long int value if successful,0 if the get fails. For example if the next is at the end of the Logger entry.
void* SPHLFEntryGetNextPtr ( SPHLFEntryHandle_t handle)
inline

Return the next void* from the entry via the current next value pointer. Leading bytes may be skipped to get the required alignment. The internal next value pointer is advanced to the next location.

Parameters
handleEntry Handle for an allocated entry.
Returns
the void* value if successful, 0 (NULL) if the get fails. For example if the next is at the end of the Logger entry.
short int SPHLFEntryGetNextShort ( SPHLFEntryHandle_t handle)
inline

Return the next short int from the entry via the current next value pointer. Leading bytes may be skipped to get the required alignment. The internal next value pointer is advanced to the next location.

Parameters
handleEntry Handle for an allocated entry.
Returns
the short int value if successful, 0 if the get fails. For example if the next is at the end of the Logger entry.
char* SPHLFEntryGetNextString ( SPHLFEntryHandle_t handle)
inline

Return the pointer to the next C string from the logger entry via the current next value pointer. The internal next value pointer is advanced to the next location after the string NUL char.

Parameters
handleEntry Handle for an allocated entry.
Returns
the C string pointer value if successful, 0 (NULL) if the get fails. For example if the next is at the end of the Logger entry.
void* SPHLFEntryGetStructPtr ( SPHLFEntryHandle_t handle,
unsigned long  __size,
unsigned long  __align 
)
inline

Return the correctly aligned pointer for a struct or array starting at the next free location within the entry.

The entries next pointer is adjusted for alignment and returned. The entries next pointer and remaining fields are updated for the next field following the struct/array.

Note
The SPHENTRYGETSTRUCTPTR can be used to insure the correct usage sizeof and alignof to provide values for the __size and __align parameters.
Parameters
handleEntry Handle for an allocated entry.
__sizeof the struct/array to allocate.
__alignalignment requirement of the struct/array space to allocated.
Returns
address of the allocated free space. NULL indicates failure. For example if remaining entry space is insufficient to hold the struct at the required alignment.
SPHLFEntryHeader_t* SPHLFEntryHeader ( SPHLFEntryHandle_t handlespace)
inline

Return the address for the entry header specified by the entry handle.

Parameters
handlespaceEntry Handle for an allocated entry.
Returns
the address from the entry header, if the entry was valid. Otherwise return NULL.
int SPHLFEntryIsComplete ( SPHLFEntryHandle_t handlespace)
inline

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

Parameters
handlespaceEntry Handle for an allocated entry.
Returns
true if the entry was complete (SPHLFLoggerEntryComplete has been called fo this entry). Otherwise False.
int SPHLFEntryIsTimestamped ( SPHLFEntryHandle_t handlespace)
inline

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

Parameters
handlespaceEntry Handle for an allocated entry.
Returns
true if the entry was time stamped. Otherwise False.
sphpid16_t SPHLFEntryPID ( SPHLFEntryHandle_t handlespace)
inline

Return the process ID for the entry specified by the entry handle.

Parameters
handlespaceEntry Handle for an allocated entry.
Returns
the PID from the entry, if the entry was valid and time stamped. Otherwise return 0.
int SPHLFEntryStrongComplete ( SPHLFEntryHandle_t handlespace)
inline

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
handlespaceEntry Handle for an allocated entry.
Returns
a 0 value indicates success.
int SPHLFEntrySubcat ( SPHLFEntryHandle_t handlespace)
inline

Return the entry sub-category for the entry specified by the entry handle.

Parameters
handlespaceEntry Handle for an allocated entry.
Returns
the sub-category from the entry, if the entry was valid. Otherwise return 0.
sphpid16_t SPHLFEntryTID ( SPHLFEntryHandle_t handlespace)
inline

Return the thread ID for the entry specified by the entry handle.

Parameters
handlespaceEntry Handle for an allocated entry.
Returns
the TID from the entry, if the entry was valid and time stamped. Otherwise return 0.
sphtimer_t SPHLFEntryTimeStamp ( SPHLFEntryHandle_t handlespace)
inline

Return the time stamp value for the entry specified by the entry handle.

Parameters
handlespaceEntry Handle for an allocated entry.
Returns
the time stamp value from the entry, if the entry was valid and time stamped. Otherwise return 0.
int SPHLFEntryWeakComplete ( SPHLFEntryHandle_t handlespace)
inline

Marks the entry specified by the entry handle as complete. No memory barriers are performance. On out-of-order machines there are no guarantee that all previous stores by this thread are visible to other threads.

Parameters
handlespaceEntry Handle for an allocated entry.
Returns
a 0 value indicates success.