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"

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:

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.

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

#include <sphdirectpcqueue.h>
  int *array;
  int data1, data2, data3;
  handle = SPHSinglePCQueueGetNextCompleteDirectSpin (cqueue);
  if (handle)
    {
      array = (int *) SPHLFEntryDirectGetFreePtr (handle);
      data1 = array[0];
      data2 = array[1];
      data3 = array[2];
      if (SPHSinglePCQueueFreeNextEntryDirect (cqueue, handle))
        {
          // 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:

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.

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

directHandle Entry 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

directHandle	Entry Handle for an allocated entry.
entry_template	from SPHSinglePCQueueGetEntryTemplate().
catcode	Category code to the completed entry.
subcode	Subcategory 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

directHandle Entry 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

directHandle	Entry Handle for an allocated entry.
alignval	required 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

directptr	current data address within Entry.
incval	size of last entry address to stepped over.
alignval	required 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

directHandle Entry 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

directHandle Entry 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

directHandle Entry 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

queue Handle 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

queue Handle 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

queue Handle 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

directHandle entry 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

queue	Handle of a producer consumer queue,
next_entry	Direct 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

queue Handle 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

queue Handle 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

queue Handle 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

queue Handle 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

queue Handle 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.

Macros

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation