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

Shared Persistent Heap, single producer single consumer queue direct API. More...

#include <stdint.h>
#include "sastype.h"
#include "sasatom.h"
#include "sphlfentry.h"
#include "sphsinglepcqueue.h"

Go to the source code of this file.

Macros

#define __C__
 ignore this macro behind the curtain
 

Typedefs

typedef void * SPHLFEntryDirect_t
 Instance of a Lock Free event direct data Handle. More...
 

Functions

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. More...
 
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. More...
 
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. More...
 
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. More...
 
static int SPHLFEntryDirectIsComplete (SPHLFEntryDirect_t directHandle)
 Return the status of the entry specified by the direct entry handle. More...
 
static int SPHLFEntryDirectIsTimestamped (SPHLFEntryDirect_t directHandle)
 Return the status of the entry specified by the direct entry handle. More...
 
static int SPHLFEntryDirectCategory (SPHLFEntryDirect_t directHandle)
 Return the entry category for the entry specified by the direct entry handle. More...
 
static int SPHLFEntryDirectSubcat (SPHLFEntryDirect_t directHandle)
 Return the entry sub-category for the entry specified by the direct entry handle. More...
 
__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. More...
 
__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. More...
 
__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. More...
 
__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. More...
 
__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. More...
 
__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. More...
 
__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. More...
 
__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. More...
 
__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. More...
 
__C__ int SPHSinglePCQueueEntryIsCompleteDirect (SPHLFEntryDirect_t directHandle)
 Return the status of the entry specified by the direct entry handle. More...
 

Detailed Description

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:

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);
int *array;
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:

int *array;
int data1, data2, data3;
if (handle)
{
array = (int *) SPHLFEntryDirectGetFreePtr (handle);
data1 = array[0];
data2 = array[1];
data3 = array[2];
{
// complete handling of message
}
else
{ // error handling
printf ("SPHSinglePCQueueFreeNextEntry() = failed\n");
}
}
else
{ // error handling
printf ("SPHSinglePCQueueGetNextCompleteDirectSpin() = failed\n");
}

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:

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.

Typedef Documentation

typedef void* SPHLFEntryDirect_t

Instance of a Lock Free event direct data Handle.

Contains fields required to: locate the entry, record the total space allocated to the entry, and manage the next location within the entry and remaining storage.

Entry Handles should be allocated in private (local stack) storage
to allow concurrent access to independent entries from multiple threads.

Function Documentation

static int SPHLFEntryDirectCategory ( SPHLFEntryDirect_t  directHandle)
inlinestatic

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

Parameters
directHandleEntry Handle for an allocated entry.
Returns
the category from the entry, if the entry was valid. Otherwise return 0.
static int SPHLFEntryDirectComplete ( SPHLFEntryDirect_t  directHandle,
sphLFEntryID_t  entry_template,
int  catcode,
int  subcode 
)
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 by this thread to this entry are complete.

Parameters
directHandleEntry Handle for an allocated entry.
entry_templatefrom SPHSinglePCQueueGetEntryTemplate().
catcodeCategory code to the completed entry.
subcodeSubcategory code to the completed entry.
Returns
a 1 value indicates success.
static void* SPHLFEntryDirectGetFreePtr ( SPHLFEntryDirect_t  directHandle)
inlinestatic

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.

Warning
This function should be used carefully. It is may not provide the correct alignment for the data that follow and does not manage the space within the direct entry, if multiple application functions may update the same entry.
Parameters
directHandleEntry Handle for an allocated entry.
Returns
address the entries free space.
static void* SPHLFEntryDirectGetPtrAligned ( SPHLFEntryDirect_t  directHandle,
size_t  alignval 
)
inlinestatic

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.

Warning
This function does not manage the space within the direct entry, this may be an issue if multiple application functions update the same entry.
Parameters
directHandleEntry Handle for an allocated entry.
alignvalrequired alignment of the next value to be added.
Returns
address the entries free space.
static void* SPHLFEntryDirectIncAndAlign ( void *  directptr,
size_t  incval,
size_t  alignval 
)
inlinestatic

Return the next free byte address within direct entry specified by a current address within that direct entry.

Warning
This function does not manage the space within the direct entry, this may be an issue if multiple application functions update the same entry.
Parameters
directptrcurrent data address within Entry.
incvalsize of last entry address to stepped over.
alignvalrequired alignment of the next value to be added.
Returns
next address within the entry with require alignment.
static int SPHLFEntryDirectIsComplete ( SPHLFEntryDirect_t  directHandle)
inlinestatic

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

Parameters
directHandleEntry Handle for an allocated entry.
Returns
true if the entry was complete (SPHLFLoggerEntryComplete has been called fo this entry). Otherwise False.
static int SPHLFEntryDirectIsTimestamped ( SPHLFEntryDirect_t  directHandle)
inlinestatic

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

Parameters
directHandleEntry Handle for an allocated entry.
Returns
true if the entry was time stamped. Otherwise False.
static int SPHLFEntryDirectSubcat ( SPHLFEntryDirect_t  directHandle)
inlinestatic

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

Parameters
directHandleEntry Handle for an allocated entry.
Returns
the sub-category from the entry, if the entry was valid. Otherwise return 0.
__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.

The allocation size is the stride set when the PC queue was initialized/created. The Entry status and length are stored in the header of the new entry. Returns an dire ctentry handle which allows the application to insert application specific data into the entry via the sphlfentry.h API. If the specified queue is full the allocation may fail.

Note
The queue entry is not ready for access by the Consumer thread, until additional application data is inserted and the entry is completed (via SPHLFEntryDirectComplete). Category and Subcategory may be supplied as the entry is completed.
Parameters
queueHandle of a producer consumer queue.
Returns
Direct handle of the initialized queue entry, or 0 (NULL) if the allocation failed. For example the Allocate may fail if the queue is full.
__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.

The allocation size is the stride set when the PC queue was initialized/created. The Entry status and length are stored in the header of the new entry. Returns an dire ctentry handle which allows the application to insert application specific data into the entry via the sphlfentry.h API. If the specified queue is full the allocation may fail.

Note
The queue entry is not ready for access by the Consumer thread, until additional application data is inserted and the entry is completed (via SPHLFEntryDirectComplete). Category and Subcategory may be supplied as the entry is completed.
Parameters
queueHandle of a producer consumer queue.
Returns
Direct handle of the initialized queue entry, or 0 (NULL) if the allocation failed. For example the Allocate may fail if the queue is full.
__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.

The allocation size is the stride set when the PC queue was initialized/created. The Entry status and length are stored in the header of the new entry. Returns an dire ctentry handle which allows the application to insert application specific data into the entry via the sphlfentry.h API. If the specified queue is full the allocation may fail.

Note
The queue entry is not ready for access by the Consumer thread, until additional application data is inserted and the entry is completed (via SPHLFEntryDirectComplete). Category and Subcategory may be supplied as the entry is completed.
Parameters
queueHandle of a producer consumer queue.
Returns
Direct handle of the initialized queue entry, or 0 (NULL) if the allocation failed. For example the Allocate may fail if the queue is full.
__C__ int SPHSinglePCQueueEntryIsCompleteDirect ( SPHLFEntryDirect_t  directHandle)

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

Parameters
directHandleentry Handle for an allocated entry.
Returns
true if the entry was complete (SPHSinglePCQueueEntryComplete has been called for this entry). Otherwise False.
__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.

Mark the current queue tail entry as free (unallocated and invalid) and bump the queue tail pointer to the next entry. If the specified queue is empty or the current tail entry is not yet completed the Free may fail.

Warning
The Consumer thread should not touch or modify a queue entry after calling FreeEntry. This is important to both correctness and performance.
Parameters
queueHandle of a producer consumer queue,
next_entryDirect handle of the queue entry to free.
Returns
True for successful tail free, otherwise indicated failure. For example the Free may fail if the queue is empty or the next tail entry is not yet completed.
__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.

Parameters
queueHandle of a producer consumer queue.
Returns
the entry template for this queue or 0 if not a valid SPHSinglePCQueue_t.
__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.

Returns an direct entry handle which allows the application to access the application specific data inserted by the produced thread. If the specified queue is empty or the next queue is not yet completed the get may fail.

Parameters
queueHandle of a producer consumer queue.
Returns
Direct Handle of the initialized logger entry, or 0 (NULL) if the get failed. For example the Get may fail if the queue is empty or the next tail entry is not yet completed.
__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.

Returns an direct entry handle which allows the application to access the application specific data inserted by the produced thread. If the specified queue is empty or the next queue is not yet completed, spin until data is ready.

Parameters
queueHandle of a producer consumer queue.
Returns
Direct Handle of the initialized logger entry, or 0 (NULL) if the get failed. For example the Get id the queue is not actually a SPHSinglePCQueue_t.
__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.

Returns an direct entry handle which allows the application to access the application specific data inserted by the produced thread. If the specified queue is empty or the next queue is not yet completed, spin until data is ready. While spinning use appropriate arch specific instructions to free up core resources for other threads.

Parameters
queueHandle of a producer consumer queue.
Returns
Direct Handle of the initialized logger entry, or 0 (NULL) if the get failed. For example the Get id the queue is not actually a SPHSinglePCQueue_t.
__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.

Returns an direct entry handle which allows the application to access the entry allocated by the produced thread. If the specified queue is empty or the next queue is not yet allocated the get may fail. Returning a entry does not mean the the producer has completed the entry and the consumer wait/spin (SPHLFEntryDirectIsComplete) for the entry to become complete.

Parameters
queueHandle of a producer consumer queue.
Returns
Direct Handle of the initialized logger entry, or 0 (NULL) if the get failed. For example the Get may fail if the queue is empty or the next tail entry is not yet allocated.