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"

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

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

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

static int	SPHLFEntryIsComplete (SPHLFEntryHandle_t *handlespace)
	Return the status of the entry specified by the entry handle. More...

static int	SPHLFEntryIsTimestamped (SPHLFEntryHandle_t *handlespace)
	Return the status of the entry specified by the entry handle. More...

static sphtimer_t	SPHLFEntryTimeStamp (SPHLFEntryHandle_t *handlespace)
	Return the time stamp value for the entry specified by the entry handle. More...

static sphpid16_t	SPHLFEntryPID (SPHLFEntryHandle_t *handlespace)
	Return the process ID for the entry specified by the entry handle. More...

static sphpid16_t	SPHLFEntryTID (SPHLFEntryHandle_t *handlespace)
	Return the thread ID for the entry specified by the entry handle. More...

static SPHLFEntryHeader_t *	SPHLFEntryHeader (SPHLFEntryHandle_t *handlespace)
	Return the address for the entry header specified by the entry handle. More...

static int	SPHLFEntryCategory (SPHLFEntryHandle_t *handlespace)
	Return the entry category for the entry specified by the entry handle. More...

static int	SPHLFEntrySubcat (SPHLFEntryHandle_t *handlespace)
	Return the entry sub-category for the entry specified by the entry handle. More...

static void *	SPHLFEntryGetFreePtr (SPHLFEntryHandle_t *handle)
	Return the first free byte address for the entry specified by the entry handle. More...

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

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

static int	SPHLFEntryAddString (SPHLFEntryHandle_t handle, char value)
	Insert a C string at the next free location within the entry. More...

static int	SPHLFEntryAddChar (SPHLFEntryHandle_t *handle, char value)
	Insert a character at the next free location within the entry. More...

static int	SPHLFEntryAddShort (SPHLFEntryHandle_t *handle, short int value)
	Insert a short int at the next free location within the entry. More...

static int	SPHLFEntryAddInt (SPHLFEntryHandle_t *handle, int value)
	Insert a int at the next free location within the entry. More...

static int	SPHLFEntryAddLong (SPHLFEntryHandle_t *handle, long value)
	Insert a long int at the next free location within the entry. More...

static int	SPHLFEntryAddPtr (SPHLFEntryHandle_t handle, void value)
	Insert a void* at the next free location within the entry. More...

static int	SPHLFEntryAddLongLong (SPHLFEntryHandle_t *handle, long long value)
	Insert a long long int at the next free location within the entry. More...

static int	SPHLFEntryAddFloat (SPHLFEntryHandle_t *handle, float value)
	Insert a float at the next free location within the entry. More...

static int	SPHLFEntryAddDouble (SPHLFEntryHandle_t *handle, double value)
	Insert a double at the next free location within the entry. More...

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

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

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

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

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

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

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

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

static 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

static int SPHLFEntryAddChar	(	SPHLFEntryHandle_t *	handle,
		char	value
	)

inlinestatic

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

Parameters

handle	Entry Handle for an allocated entry.
value	a char value.

Returns: 0 if successful, -1 if the insert fails. For example if remaining entry space is insufficient to hold a char.

static int SPHLFEntryAddDouble	(	SPHLFEntryHandle_t *	handle,
		double	value
	)

inlinestatic

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

Parameters

handle	Entry Handle for an allocated entry.
value	a 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.

static int SPHLFEntryAddFloat	(	SPHLFEntryHandle_t *	handle,
		float	value
	)

inlinestatic

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

Parameters

handle	Entry Handle for an allocated entry.
value	a 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.

static int SPHLFEntryAddInt	(	SPHLFEntryHandle_t *	handle,
		int	value
	)

inlinestatic

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

Parameters

handle	Entry Handle for an allocated entry.
value	a 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.

static int SPHLFEntryAddLong	(	SPHLFEntryHandle_t *	handle,
		long	value
	)

inlinestatic

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

Parameters

handle	Entry Handle for an allocated entry.
value	a 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.

static int SPHLFEntryAddLongLong	(	SPHLFEntryHandle_t *	handle,
		long long	value
	)

inlinestatic

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

Parameters

handle	Entry Handle for an allocated entry.
value	a 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.

static int SPHLFEntryAddPtr	(	SPHLFEntryHandle_t *	handle,
		void *	value
	)

inlinestatic

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

Parameters

handle	Entry Handle for an allocated entry.
value	a 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.

static int SPHLFEntryAddShort	(	SPHLFEntryHandle_t *	handle,
		short int	value
	)

inlinestatic

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

Parameters

handle	Entry Handle for an allocated entry.
value	a 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.

static int SPHLFEntryAddString	(	SPHLFEntryHandle_t *	handle,
		char *	value
	)

inlinestatic

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

Parameters

handle	Entry Handle for an allocated entry.
value	pointer 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.

static void* SPHLFEntryAllocStruct	(	SPHLFEntryHandle_t *	handle,
		unsigned long	__size,
		unsigned long	__align
	)

inlinestatic

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

handle	Entry Handle for an allocated entry.
__size	of the struct/array to allocate.
__align	alignment 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.

static int SPHLFEntryCategory ( SPHLFEntryHandle_t * handlespace )

inlinestatic

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

Parameters

handlespace Entry Handle for an allocated entry.

Returns: the category from the entry, if the entry was valid. Otherwise return 0.

static int SPHLFEntryComplete ( SPHLFEntryHandle_t * handlespace )

inlinestatic

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

handlespace Entry Handle for an allocated entry.

Returns: a 0 value indicates success.

static void* SPHLFEntryGetFreePtr ( SPHLFEntryHandle_t * handle )

inlinestatic

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

handle Entry Handle for an allocated entry.

Returns: address the entries free space.

static char SPHLFEntryGetNextChar ( SPHLFEntryHandle_t * handle )

inlinestatic

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

handle Entry 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.

static double SPHLFEntryGetNextDouble ( SPHLFEntryHandle_t * handle )

inlinestatic

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

handle Entry 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.

static float SPHLFEntryGetNextFloat ( SPHLFEntryHandle_t * handle )

inlinestatic

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

handle Entry 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.

static int SPHLFEntryGetNextInt ( SPHLFEntryHandle_t * handle )

inlinestatic

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

handle Entry 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.

static long SPHLFEntryGetNextLong ( SPHLFEntryHandle_t * handle )

inlinestatic

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

handle Entry 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.

static long long SPHLFEntryGetNextLongLong ( SPHLFEntryHandle_t * handle )

inlinestatic

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

handle Entry 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.

static void* SPHLFEntryGetNextPtr ( SPHLFEntryHandle_t * handle )

inlinestatic

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

handle Entry 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.

static short int SPHLFEntryGetNextShort ( SPHLFEntryHandle_t * handle )

inlinestatic

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

handle Entry 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.

static char* SPHLFEntryGetNextString ( SPHLFEntryHandle_t * handle )

inlinestatic

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

handle Entry 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.

static void* SPHLFEntryGetStructPtr	(	SPHLFEntryHandle_t *	handle,
		unsigned long	__size,
		unsigned long	__align
	)

inlinestatic

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

handle	Entry Handle for an allocated entry.
__size	of the struct/array to allocate.
__align	alignment 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.

static SPHLFEntryHeader_t* SPHLFEntryHeader ( SPHLFEntryHandle_t * handlespace )

inlinestatic

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

Parameters

handlespace Entry Handle for an allocated entry.

Returns: the address from the entry header, if the entry was valid. Otherwise return NULL.

static int SPHLFEntryIsComplete ( SPHLFEntryHandle_t * handlespace )

inlinestatic

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

Parameters

handlespace Entry Handle for an allocated entry.

Returns: true if the entry was complete (SPHLFLoggerEntryComplete has been called fo this entry). Otherwise False.

static int SPHLFEntryIsTimestamped ( SPHLFEntryHandle_t * handlespace )

inlinestatic

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

Parameters

handlespace Entry Handle for an allocated entry.

Returns: true if the entry was time stamped. Otherwise False.

static sphpid16_t SPHLFEntryPID ( SPHLFEntryHandle_t * handlespace )

inlinestatic

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

Parameters

handlespace Entry Handle for an allocated entry.

Returns: the PID from the entry, if the entry was valid and time stamped. Otherwise return 0.

static int SPHLFEntryStrongComplete ( SPHLFEntryHandle_t * handlespace )

inlinestatic

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

handlespace Entry Handle for an allocated entry.

Returns: a 0 value indicates success.

static int SPHLFEntrySubcat ( SPHLFEntryHandle_t * handlespace )

inlinestatic

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

Parameters

handlespace Entry Handle for an allocated entry.

Returns: the sub-category from the entry, if the entry was valid. Otherwise return 0.

static sphpid16_t SPHLFEntryTID ( SPHLFEntryHandle_t * handlespace )

inlinestatic

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

Parameters

handlespace Entry Handle for an allocated entry.

Returns: the TID from the entry, if the entry was valid and time stamped. Otherwise return 0.

static sphtimer_t SPHLFEntryTimeStamp ( SPHLFEntryHandle_t * handlespace )

inlinestatic

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

Parameters

handlespace Entry Handle for an allocated entry.

Returns: the time stamp value from the entry, if the entry was valid and time stamped. Otherwise return 0.

static int SPHLFEntryWeakComplete ( SPHLFEntryHandle_t * handlespace )

inlinestatic

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

handlespace Entry Handle for an allocated entry.

Returns: a 0 value indicates success.

Classes

Macros

Typedefs

Functions

Detailed Description

Function Documentation