|
static int | SPHLFEntryDirectComplete (SPHLFEntryDirect_t directHandle, sphLFEntryID_t entry_template, int catcode, int subcode) |
| 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 by this thread to this entry are complete.
|
|
static void * | SPHLFEntryDirectGetFreePtr (SPHLFEntryDirect_t directHandle) |
| Return the first free byte address for the direct entry specified by the direct entry handle. This is normally the byte after the sphLFEntry_t.
|
|
static void * | SPHLFEntryDirectGetPtrAligned (SPHLFEntryDirect_t directHandle, size_t alignval) |
| Return the first free byte address, with required alignment, within the direct entry specified by the direct entry handle. This is normally the address after the sphLFEntry_t plus alignment padding.
|
|
static void * | SPHLFEntryDirectIncAndAlign (void *directptr, size_t incval, size_t alignval) |
| Return the next free byte address within direct entry specified by a current address within that direct entry.
|
|
static int | SPHLFEntryDirectIsComplete (SPHLFEntryDirect_t directHandle) |
| Return the status of the entry specified by the direct entry handle.
|
|
static int | SPHLFEntryDirectIsTimestamped (SPHLFEntryDirect_t directHandle) |
| Return the status of the entry specified by the direct entry handle.
|
|
static int | SPHLFEntryDirectCategory (SPHLFEntryDirect_t directHandle) |
| Return the entry category for the entry specified by the direct entry handle.
|
|
static int | SPHLFEntryDirectSubcat (SPHLFEntryDirect_t directHandle) |
| Return the entry sub-category for the entry specified by the direct entry handle.
|
|
__C__ sphLFEntryID_t | SPHSinglePCQueueGetEntryTemplate (SPHSinglePCQueue_t queue) |
| Return the entry template for an existing Lock Free Single Producer Single Consumer Queue. This template is used later to mark an allocated entry complete.
|
|
__C__ SPHLFEntryDirect_t | SPHSinglePCQueueAllocStrideDirect (SPHSinglePCQueue_t queue) |
| 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__ SPHLFEntryDirect_t | SPHSinglePCQueueAllocStrideDirectSpin (SPHSinglePCQueue_t queue) |
| 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. If space is not Immediately available, spin until it is.
|
|
__C__ SPHLFEntryDirect_t | SPHSinglePCQueueAllocStrideDirectSpinPause (SPHSinglePCQueue_t queue) |
| 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. If space is not Immediately available, spin until it is. While spinning use appropriate arch specific instructions to free up core resources for other threads.
|
|
__C__ SPHLFEntryDirect_t | SPHSinglePCQueueGetNextCompleteDirectSpin (SPHSinglePCQueue_t queue) |
| Allows the consumer to get the next completed queue entry from the specified single producer single consumer queue.
|
|
__C__ SPHLFEntryDirect_t | SPHSinglePCQueueGetNextCompleteDirectSpinPause (SPHSinglePCQueue_t queue) |
| Allows the consumer to get the next completed queue entry from the specified single producer single consumer queue.
|
|
__C__ SPHLFEntryDirect_t | SPHSinglePCQueueGetNextCompleteDirect (SPHSinglePCQueue_t queue) |
| Allows the consumer to get the next completed queue entry from the specified single producer single consumer queue.
|
|
__C__ int | SPHSinglePCQueueFreeNextEntryDirect (SPHSinglePCQueue_t queue, SPHLFEntryDirect_t next_entry) |
| Allows the consumer to free the queue entry it just processed (using SPHSinglePCQueueGetNextComplete), from the specified single producer single consumer queue.
|
|
__C__ SPHLFEntryDirect_t | SPHSinglePCQueueGetNextEntryDirect (SPHSinglePCQueue_t queue) |
| Allows the consumer to get the next allocated queue entry from the specified single producer single consumer queue.
|
|
__C__ int | SPHSinglePCQueueEntryIsCompleteDirect (SPHLFEntryDirect_t directHandle) |
| Return the status of the entry specified by the direct entry handle.
|
|
Shared Persistent Heap, single producer single consumer queue direct API.
For shared memory multi-thread/multi-core applications.
This implementation is based on the Lock
Free Producer/Consumer Queue (SPHSinglePCQueue_t) but
simplifies access to the Entry for lower latency.
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.
\code
#include <sphdirectpcqueue.h>
sphLFEntryID_t entry_tmp;
// only need to do this once per pcqueue and so should be // outside of the primary producer message loop. entry_tmp = SPHSinglePCQueueGetEntryTemplate(pqueue);
SPHLFEntryDirect_t handle;
int *array;
handle = SPHSinglePCQueueAllocStrideDirectSpin (pqueue); if (handle) { array = (int *) SPHLFEntryDirectGetFreePtr (handle); array[0] = val1; array[1] = val2; array[2] = val3; SPHLFEntryDirectComplete (handle, entry_tmp, 1, 2); } else { // error handling }
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.
int *array;
int data1, data2, data3;
if (handle)
{
data1 = array[0];
data2 = array[1];
data3 = array[2];
{
}
else
{
printf ("SPHSinglePCQueueFreeNextEntry() = failed\n");
}
}
else
{
printf ("SPHSinglePCQueueGetNextCompleteDirectSpin() = failed\n");
}
Shared Persistent Heap, single producer single consumer queue direct API.
static void * SPHLFEntryDirectGetFreePtr(SPHLFEntryDirect_t directHandle)
Return the first free byte address for the direct entry specified by the direct entry handle....
Definition sphdirectpcqueue.h:192
__C__ SPHLFEntryDirect_t SPHSinglePCQueueGetNextCompleteDirectSpin(SPHSinglePCQueue_t queue)
Allows the consumer to get the next completed queue entry from the specified single producer single c...
__C__ int SPHSinglePCQueueFreeNextEntryDirect(SPHSinglePCQueue_t queue, SPHLFEntryDirect_t next_entry)
Allows the consumer to free the queue entry it just processed (using SPHSinglePCQueueGetNextComplete)...
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 byte entry header with:
- Entry status and length.
- Entry identifying Category and SubCategory codes.
Any additional storage allocated to the entry (after the header) is available for application specific data. This API also provides a direct pointer mechanism to store application data. 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.