Shared Persistent Heap, single producer single consumer queue. For shared memory multi-thread/multi-core applications. This implementation uses atomic operations to implement Lock Free Producer/Consumer queues (SPHSinglePCQueue_t).
More...
|
__C__ SPHSinglePCQueue_t | SPHSinglePCQueueInit (void *buf_seg, block_size_t buf_size) |
| Initialize a shared storage block as a Lock Free PC Queue.
|
|
__C__ SPHSinglePCQueue_t | SPHSinglePCQueueInitWithStride (void *buf_seg, block_size_t buf_size, unsigned short entry_stride, unsigned int options) |
| Initialize a shared storage block as a Lock Free Single Producer Single Consumer Queue with a fixed entry stride.
|
|
__C__ SPHSinglePCQueue_t | SPHSinglePCQueueCreate (block_size_t buf_size) |
| Allocate and initialize a shared storage block as a Lock Free Single Producer Single Consumer Queue.
|
|
__C__ SPHSinglePCQueue_t | SPHSinglePCQueueCreateWithStride (block_size_t buf_size, unsigned short stride) |
| Allocate and initialize a shared storage block as a Lock Free Single Producer Single Consumer Queue.
|
|
__C__ int | SPHSinglePCQueueGetStride (SPHSinglePCQueue_t queue) |
| Return the entry stride for an existing Lock Free Single Producer Single Consumer Queue.
|
|
__C__ void * | SPHSinglePCQueueAllocRaw (SPHSinglePCQueue_t queue) |
| Allows the Producer thread to return the address of a (raw) queue entry allocated from the specified Single Producer Single Consumer Queue.
|
|
__C__ SPHLFEntryHandle_t * | SPHSinglePCQueueAllocStrideEntry (SPHSinglePCQueue_t queue, int catcode, int subcode, SPHLFEntryHandle_t *handlespace) |
| Allows the producer thread to allocate and initialize the header of a queue entry for access. The allocation is from the specified Single Producer Single Consumer Queue.
|
|
__C__ SPHLFEntryHandle_t * | SPHSinglePCQueueAllocStrideTimeStamped (SPHSinglePCQueue_t queue, int catcode, int subcode, SPHLFEntryHandle_t *handlespace) |
| Allows the producer thread to allocate and initialize the header, of a queue entry for access. The allocation is from the specified Single Producer Single Consumer Queue.
|
|
__C__ int | SPHSinglePCQueueEntryComplete (SPHLFEntryHandle_t *entryhandle) |
| Allows the producer thread to mark the queue entry, specified by the entry handle, as complete. This makes the queue entry accessible to the consumer thread.
|
|
__C__ int | SPHSinglePCQueueEntryIsComplete (SPHLFEntryHandle_t *entryhandle) |
| Return the status of the entry specified by the entry handle.
|
|
__C__ SPHLFEntryHandle_t * | SPHSinglePCQueueGetNextComplete (SPHSinglePCQueue_t queue, SPHLFEntryHandle_t *handlespace) |
| Allows the consumer to get the next completed queue entry from the specified single producer single consumer queue.
|
|
__C__ int | SPHSinglePCQueueFreeNextEntry (SPHSinglePCQueue_t queue) |
| Allows the consumer to free the queue entry it just processed (using SPHSinglePCQueueGetNextComplete), from the specified single producer single consumer queue.
|
|
__C__ int | SPHSinglePCQueueEmpty (SPHSinglePCQueue_t queue) |
| Return the status of the specified queue.
|
|
__C__ block_size_t | SPHSinglePCQueueFreeSpace (SPHSinglePCQueue_t queue) |
| Returns the amount of free space (in bytes) remaining in the specified queue.
|
|
__C__ int | SPHSinglePCQueueFull (SPHSinglePCQueue_t queue) |
| Return the status of the specified queue.
|
|
__C__ int | SPHSinglePCQueueResetAsync (SPHSinglePCQueue_t queue) |
| Resets the specific queue to empty state asynchronously (without locking or atomic updates).
|
|
__C__ int | SPHSinglePCQueuePrefetch (SPHSinglePCQueue_t queue) |
| Prefetch pages from the specific queue.
|
|
__C__ int | SPHSinglePCQueueSetCachePrefetch (SPHSinglePCQueue_t queue, int prefetch) |
| Set the cache-line prefetch options for entry allocate.
|
|
__C__ int | SPHSinglePCQueueDestroy (SPHSinglePCQueue_t queue) |
| Destroys the queue and frees the SAS storage for reuse.
|
|
Shared Persistent Heap, single producer single consumer queue. For shared memory multi-thread/multi-core applications. This implementation uses atomic operations to implement Lock Free Producer/Consumer queues (SPHSinglePCQueue_t).
!
This API supports atomic allocation of storage for queue entries for zero copy persistence and sharing. Zero copy queues divides the process of producing a queue entry in to three steps:
- Allocate the queue entry (and initialize the header)
- Use the return entry handle to fill in application specific data.
- Marks the entry complete in the header.
typedef struct data_struct11 {
double field0;
int field1;
int field2;
void *field3;
} data_struct11;
if (handle)
{
data_struct11 *struct_ptr;
{
printf("error SPHLFEntryAddPtr(%p, sas_data_buff) failed)\n",
handle);
}
{
printf("error SPHLFEntryAddInt(%p, data_int1) failed)\n",
handle);
}
{
printf("error SPHLFEntryAddString(%p, data_string1) failed)\n",
handle);
}
if (struct_ptr)
{
struct_ptr->field0 = data_double1;
struct_ptr->field1 = data_int2;
struct_ptr->field2 = data_int3;
struct_ptr->field3 = (void*)sas_data_buff2;
} else {
printf("error SPHENTRYALLOCSTRUCT(%p, data_struct11) failed)\n",
handle);
}
} else {
{
}
}
Shared Persistent Heap, logger/queue etc event entry status, update, and access functions.
static int SPHLFEntryAddString(SPHLFEntryHandle_t *handle, char *value)
Insert a C string at the next free location within the entry.
Definition sphlfentry.h:477
#define SPHENTRYALLOCSTRUCT(__handle, __struct)
Macro for using sizeof/__alignof__ parms with SPHLFEntryAllocStruct function.
Definition sphlfentry.h:415
static int SPHLFEntryAddInt(SPHLFEntryHandle_t *handle, int value)
Insert a int at the next free location within the entry.
Definition sphlfentry.h:576
static int SPHLFEntryAddPtr(SPHLFEntryHandle_t *handle, void *value)
Insert a void* at the next free location within the entry.
Definition sphlfentry.h:652
__C__ int SPHSinglePCQueueFull(SPHSinglePCQueue_t queue)
Return the status of the specified queue.
__C__ int SPHSinglePCQueueEntryComplete(SPHLFEntryHandle_t *entryhandle)
Allows the producer thread to mark the queue entry, specified by the entry handle,...
__C__ SPHLFEntryHandle_t * SPHSinglePCQueueAllocStrideEntry(SPHSinglePCQueue_t queue, int catcode, int subcode, SPHLFEntryHandle_t *handlespace)
Allows the producer thread to allocate and initialize the header of a queue entry for access....
Instance of a Lock Free event data Entry Handle.
Definition sphlfentry.h:115
The consumer can access queue entries once they are marked complete. The consumer:
- checks (spins) for the next allocated entry to become complete.
- uses the returned entry handle to directly access the entry contents.
- When done processing the queue entry, it marks the entry header invalid and deallocates the entry.
- This makes the next queue entry available, if any.
typedef struct data_struct11 {
double field0;
int field1;
int field2;
void *field3;
} data_struct11;
if (handle)
{
data_struct11 *struct_ptr;
if (!sas_data_buff)
{
printf("error SPHLFEntryAddPtr(%p, sas_data_buff) failed)\n",
handle);
}
if (data_string1)
{
printf("error SPHLFEntryGetNextString(%p, data_string1) failed)\n",
handle);
}
if (struct_ptr)
{
data_double1 = struct_ptr->field0;
data_int2 = struct_ptr->field1;
data_int3 = struct_ptr->field2;
sas_data_buff2 = struct_ptr->field3;
} else {
printf("error SPHENTRYALLOCSTRUCT(%p, data_struct11) failed)\n",
handle);
}
} else {
{
}
}
static int SPHLFEntryGetNextInt(SPHLFEntryHandle_t *handle)
Return the next int from the entry via the current next value pointer. Leading bytes may be skipped t...
Definition sphlfentry.h:896
static char * SPHLFEntryGetNextString(SPHLFEntryHandle_t *handle)
Return the pointer to the next C string from the logger entry via the current next value pointer....
Definition sphlfentry.h:829
static void * SPHLFEntryGetNextPtr(SPHLFEntryHandle_t *handle)
Return the next void* from the entry via the current next value pointer. Leading bytes may be skipped...
Definition sphlfentry.h:968
__C__ SPHLFEntryHandle_t * SPHSinglePCQueueGetNextComplete(SPHSinglePCQueue_t queue, SPHLFEntryHandle_t *handlespace)
Allows the consumer to get the next completed queue entry from the specified single producer single c...
__C__ int SPHSinglePCQueueFreeNextEntry(SPHSinglePCQueue_t queue)
Allows the consumer to free the queue entry it just processed (using SPHSinglePCQueueGetNextComplete)...
__C__ int SPHSinglePCQueueEmpty(SPHSinglePCQueue_t queue)
Return the status of the specified queue.
In this implementation the allocation of the entry is minimally serialized based on the assumption that only one (producer) thread will be allocating queue entries. Likewise the assumption is that there is only one consumer thread per SPHSinglePCQueue_t instance. This allows independent producer/consumer thread pairs to interact with a queue instance with minimum synchronization and overhead.
As an option the queue entry allocator will fill in a 4 or 16 byte entry header with:
- Entry status and length.
- Entry identifying Category and SubCategory codes.
- Process and Thread Ids.
- High resolution timestamp.
Any additional storage allocated to the entry (after the header) 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. The API provides a completion function (SPHSinglePCQueueEntryComplete) which provides any memory barriers required by the platform and marks the entry complete.
The API support simple circular queues and requires a constant entry stride. A stride that matches or is multiple of the cache line size can improve performance by avoiding "false sharing" of cache lines containing multiple queue entries across cores/sockets.
- Todo:
- Additional work will include automatic pacing with Hysteresis