sphlflogentry.h File Reference

Shared Persistent Heap, logger entry status, update and access functions. More...

`#include <string.h>`
`#include "sasatom.h"`
`#include "sphlflogger.h"`

Go to the source code of this file.

## Macros

#define | SPHLOGENTRYGETSTRUCTPTR(__handle, __struct) SPHLFlogEntryGetStructPtr(__handle, sizeof(__struct), __alignof__(__struct))
| Macro for using sizeof/__alignof__ parms with SPHLFlogEntryGetStructPtr function.
#define | SPHLOGENTRYALLOCSTRUCT(__handle, __struct) SPHLFlogEntryAllocStruct(__handle, sizeof(__struct), __alignof__(__struct))
| Macro for using sizeof/__alignof__ parms with SPHLFlogEntryAllocStruct function.

## Functions

static int | SPHLFLogEntryStrongComplete (SPHLFLoggerHandle_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 | SPHLFLogEntryWeakComplete (SPHLFLoggerHandle_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 | SPHLFLogEntryComplete (SPHLFLoggerHandle_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. On out-of-order machines this barrier does not guarantee that all previous stores by this thread are visible to other threads. More...
static int | SPHLFLogEntryIsComplete (SPHLFLoggerHandle_t *handlespace)
| Return the status of the entry specified by the entry handle. More...
static int | SPHLFLogEntryIsTimestamped (SPHLFLoggerHandle_t *handlespace)
| Return the status of the entry specified by the entry handle. More...
static sphtimer_t | SPHLFLogEntryTimeStamp (SPHLFLoggerHandle_t *handlespace)
| Return the time stamp value for the entry specified by the entry handle. More...
static sphpid16_t | SPHLFLogEntryPID (SPHLFLoggerHandle_t *handlespace)
| Return the process ID for the entry specified by the entry handle. More...
static sphpid16_t | SPHLFLogEntryTID (SPHLFLoggerHandle_t *handlespace)
| Return the thread ID for the entry specified by the entry handle. More...
static SPHLFLogHeader_t * | SPHLFLogEntryHeader (SPHLFLoggerHandle_t *handlespace)
| Return the address for the entry header specified by the entry handle. More...
static int | SPHLFLogEntryCategory (SPHLFLoggerHandle_t *handlespace)
| Return the entry category for the entry specified by the entry handle. More...
static int | SPHLFLogEntrySubcat (SPHLFLoggerHandle_t *handlespace)
| Return the entry sub-category for the entry specified by the entry handle. More...
static void * | SPHLFLogEntryGetFreePtr (SPHLFLoggerHandle_t *handle)
| Return the address first free byte for the entry specified by the entry handle. More...
static void * | SPHLFlogEntryGetStructPtr (SPHLFLoggerHandle_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 logger entry. More...
static void * | SPHLFlogEntryAllocStruct (SPHLFLoggerHandle_t *handle, unsigned long __size, unsigned long __align)
| Allocate space for struct starting at the next free location within the logger entry. More...
static int | SPHLFlogEntryAddString (SPHLFLoggerHandle_t *handle, char *value)
| Insert a C string at the next free location within the logger entry. More...
static int | SPHLFlogEntryAddChar (SPHLFLoggerHandle_t *handle, char value)
| Insert a character at the next free location within the logger entry. More...
static int | SPHLFlogEntryAddShort (SPHLFLoggerHandle_t *handle, short int value)
| Insert a short int at the next free location within the logger entry. More...
static int | SPHLFlogEntryAddInt (SPHLFLoggerHandle_t *handle, int value)
| Insert a int at the next free location within the logger entry. More...
static int | SPHLFlogEntryAddLong (SPHLFLoggerHandle_t *handle, long value)
| Insert a long int at the next free location within the logger entry. More...
static int | SPHLFlogEntryAddPtr (SPHLFLoggerHandle_t *handle, void *value)
| Insert a void* at the next free location within the logger entry. More...
static int | SPHLFlogEntryAddLongLong (SPHLFLoggerHandle_t *handle, long long value)
| Insert a long long int at the next free location within the logger entry. More...
static int | SPHLFlogEntryAddFloat (SPHLFLoggerHandle_t *handle, float value)
| Insert a float at the next free location within the logger entry. More...
static int | SPHLFlogEntryAddDouble (SPHLFLoggerHandle_t *handle, double value)
| Insert a double at the next free location within the logger entry. More...
static char | SPHLFlogEntryGetNextChar (SPHLFLoggerHandle_t *handle)
| Return the next char from the logger entry via the current next value pointer. The internal next value pointer is advanced to the next location. More...
static char * | SPHLFlogEntryGetNextString (SPHLFLoggerHandle_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 | SPHLFlogEntryGetNextShort (SPHLFLoggerHandle_t *handle)
| Return the next short int from the logger 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 | SPHLFlogEntryGetNextInt (SPHLFLoggerHandle_t *handle)
| Return the next int from the logger 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 | SPHLFlogEntryGetNextLong (SPHLFLoggerHandle_t *handle)
| Return the next long int from the logger 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 * | SPHLFlogEntryGetNextPtr (SPHLFLoggerHandle_t *handle)
| Return the next void* from the logger 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 | SPHLFlogEntryGetNextLongLong (SPHLFLoggerHandle_t *handle)
| Return the next long long int from the logger 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 | SPHLFlogEntryGetNextFloat (SPHLFLoggerHandle_t *handle)
| Return the next float from the logger 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 | SPHLFlogEntryGetNextDouble (SPHLFLoggerHandle_t *handle)
| Return the next double from the logger 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 entry status, update and access functions.

!

Author
  Steven Munroe - initial API and implementation

       For shared memory multi-thread/multi-core applications. Once the
       SPHLFLogger_t functions have atomically allocated a Logger 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 Logger 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 (SPHLFLogEntryComplete)
       which provides and memory barriers required by the platform and
       marks the entry complete.

       \todo This API should be migrated to use the common sphlfentry.h API.

## Function Documentation

## SPHLFlogEntryAddChar()

static int SPHLFlogEntryAddChar | ( | SPHLFLoggerHandle_t * | handle,
|  | char | value
| ) |  |

inline static

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

Parameters

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

## SPHLFlogEntryAddDouble()

static int SPHLFlogEntryAddDouble | ( | SPHLFLoggerHandle_t * | handle,
|  | double | value
| ) |  |

inline static

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

Parameters

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

## SPHLFlogEntryAddFloat()

static int SPHLFlogEntryAddFloat | ( | SPHLFLoggerHandle_t * | handle,
|  | float | value
| ) |  |

inline static

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

Parameters

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

## SPHLFlogEntryAddInt()

static int SPHLFlogEntryAddInt | ( | SPHLFLoggerHandle_t * | handle,
|  | int | value
| ) |  |

inline static

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

Parameters

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

## SPHLFlogEntryAddLong()

static int SPHLFlogEntryAddLong | ( | SPHLFLoggerHandle_t * | handle,
|  | long | value
| ) |  |

inline static

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

Parameters

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

## SPHLFlogEntryAddLongLong()

static int SPHLFlogEntryAddLongLong | ( | SPHLFLoggerHandle_t * | handle,
|  | long long | value
| ) |  |

inline static

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

Parameters

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

## SPHLFlogEntryAddPtr()

static int SPHLFlogEntryAddPtr | ( | SPHLFLoggerHandle_t * | handle,
|  | void * | value
| ) |  |

inline static

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

Parameters

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

## SPHLFlogEntryAddShort()

static int SPHLFlogEntryAddShort | ( | SPHLFLoggerHandle_t * | handle,
|  | short int | value
| ) |  |

inline static

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

Parameters

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

## SPHLFlogEntryAddString()

static int SPHLFlogEntryAddString | ( | SPHLFLoggerHandle_t * | handle,
|  | char * | value
| ) |  |

inline static

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

Parameters

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

## SPHLFlogEntryAllocStruct()

static void * SPHLFlogEntryAllocStruct | ( | SPHLFLoggerHandle_t * | handle,
|  | unsigned long | __size,
|  | unsigned long | __align
| ) |  |

inline static

Allocate space for struct starting at the next free location within the logger 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 SPHLOGENTRYALLOCSTRUCT 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 SPHLFLogEntryGetFreePtr if additional data may be added later to the same entry.

Parameters

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

## SPHLFLogEntryCategory()

static int SPHLFLogEntryCategory | ( | SPHLFLoggerHandle_t * | handlespace | ) |

inline static

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

Parameters

  handlespace | Logger Entry Handle for an allocated entry.

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

## SPHLFLogEntryComplete()

static int SPHLFLogEntryComplete | ( | SPHLFLoggerHandle_t * | handlespace | ) |

inline static

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. On out-of-order machines this barrier does not guarantee that all previous stores by this thread are visible to other threads.

Parameters

  handlespace | Logger Entry Handle for an allocated entry.

Returns
  a 0 value indicates success.

## SPHLFLogEntryGetFreePtr()

static void * SPHLFLogEntryGetFreePtr | ( | SPHLFLoggerHandle_t * | handle | ) |

inline static

Return the address first free byte 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 | Logger Entry Handle for an allocated entry.

Returns
  address the entries free space.

## SPHLFlogEntryGetNextChar()

static char SPHLFlogEntryGetNextChar | ( | SPHLFLoggerHandle_t * | handle | ) |

inline static

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

Parameters

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

## SPHLFlogEntryGetNextDouble()

static double SPHLFlogEntryGetNextDouble | ( | SPHLFLoggerHandle_t * | handle | ) |

inline static

Return the next double from the logger 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 | Logger 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.

## SPHLFlogEntryGetNextFloat()

static float SPHLFlogEntryGetNextFloat | ( | SPHLFLoggerHandle_t * | handle | ) |

inline static

Return the next float from the logger 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 | Logger 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.

## SPHLFlogEntryGetNextInt()

static int SPHLFlogEntryGetNextInt | ( | SPHLFLoggerHandle_t * | handle | ) |

inline static

Return the next int from the logger 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 | Logger 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.

## SPHLFlogEntryGetNextLong()

static long SPHLFlogEntryGetNextLong | ( | SPHLFLoggerHandle_t * | handle | ) |

inline static

Return the next long int from the logger 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 | Logger 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.

## SPHLFlogEntryGetNextLongLong()

static long long SPHLFlogEntryGetNextLongLong | ( | SPHLFLoggerHandle_t * | handle | ) |

inline static

Return the next long long int from the logger 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 | Logger 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.

## SPHLFlogEntryGetNextPtr()

static void * SPHLFlogEntryGetNextPtr | ( | SPHLFLoggerHandle_t * | handle | ) |

inline static

Return the next void* from the logger 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 | Logger 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.

## SPHLFlogEntryGetNextShort()

static short int SPHLFlogEntryGetNextShort | ( | SPHLFLoggerHandle_t * | handle | ) |

inline static

Return the next short int from the logger 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 | Logger 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.

## SPHLFlogEntryGetNextString()

static char * SPHLFlogEntryGetNextString | ( | SPHLFLoggerHandle_t * | handle | ) |

inline static

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

## SPHLFlogEntryGetStructPtr()

static void * SPHLFlogEntryGetStructPtr | ( | SPHLFLoggerHandle_t * | handle,
|  | unsigned long | __size,
|  | unsigned long | __align
| ) |  |

inline static

Return the correctly aligned pointer for a struct or array starting at the next free location within the logger 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 SPHLOGENTRYGETSTRUCTPTR can be used to insure the correct usage sizeof and alignof to provide values for the __size and __align parameters.

Parameters

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

## SPHLFLogEntryHeader()

static SPHLFLogHeader_t * SPHLFLogEntryHeader | ( | SPHLFLoggerHandle_t * | handlespace | ) |

inline static

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

Parameters

  handlespace | Logger Entry Handle for an allocated entry.

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

## SPHLFLogEntryIsComplete()

static int SPHLFLogEntryIsComplete | ( | SPHLFLoggerHandle_t * | handlespace | ) |

inline static

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

Parameters

  handlespace | Logger Entry Handle for an allocated entry.

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

## SPHLFLogEntryIsTimestamped()

static int SPHLFLogEntryIsTimestamped | ( | SPHLFLoggerHandle_t * | handlespace | ) |

inline static

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

Parameters

  handlespace | Logger Entry Handle for an allocated entry.

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

## SPHLFLogEntryPID()

static sphpid16_t SPHLFLogEntryPID | ( | SPHLFLoggerHandle_t * | handlespace | ) |

inline static

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

Parameters

  handlespace | Logger Entry Handle for an allocated entry.

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

## SPHLFLogEntryStrongComplete()

static int SPHLFLogEntryStrongComplete | ( | SPHLFLoggerHandle_t * | handlespace | ) |

inline static

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 | Logger Entry Handle for an allocated entry.

Returns
  a 0 value indicates success.

## SPHLFLogEntrySubcat()

static int SPHLFLogEntrySubcat | ( | SPHLFLoggerHandle_t * | handlespace | ) |

inline static

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

Parameters

  handlespace | Logger Entry Handle for an allocated entry.

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

## SPHLFLogEntryTID()

static sphpid16_t SPHLFLogEntryTID | ( | SPHLFLoggerHandle_t * | handlespace | ) |

inline static

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

Parameters

  handlespace | Logger Entry Handle for an allocated entry.

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

## SPHLFLogEntryTimeStamp()

static sphtimer_t SPHLFLogEntryTimeStamp | ( | SPHLFLoggerHandle_t * | handlespace | ) |

inline static

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

Parameters

  handlespace | Logger 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.

## SPHLFLogEntryWeakComplete()

static int SPHLFLogEntryWeakComplete | ( | SPHLFLoggerHandle_t * | handlespace | ) |

inline static

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 | Logger Entry Handle for an allocated entry.

Returns
  a 0 value indicates success.