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

#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");
}
sphdirectpcqueue.h
Shared Persistent Heap, single producer single consumer queue direct API.
SPHLFEntryDirectGetFreePtr
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
SPHSinglePCQueueGetNextCompleteDirectSpin
__C__ SPHLFEntryDirect_t SPHSinglePCQueueGetNextCompleteDirectSpin(SPHSinglePCQueue_t queue)
Allows the consumer to get the next completed queue entry from the specified single producer single c...
SPHSinglePCQueueFreeNextEntryDirect
__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.

## Typedef Documentation

## SPHLFEntryDirect_t

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

## SPHLFEntryDirectCategory()

static int SPHLFEntryDirectCategory | ( | SPHLFEntryDirect_t | directHandle | ) |

inline static

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.

## SPHLFEntryDirectComplete()

static int SPHLFEntryDirectComplete | ( | SPHLFEntryDirect_t | directHandle,
|  | sphLFEntryID_t | entry_template,
|  | int | catcode,
|  | int | subcode
| ) |  |

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

## SPHLFEntryDirectGetFreePtr()

static void * SPHLFEntryDirectGetFreePtr | ( | SPHLFEntryDirect_t | directHandle | ) |

inline static

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.

## SPHLFEntryDirectGetPtrAligned()

static void * SPHLFEntryDirectGetPtrAligned | ( | SPHLFEntryDirect_t | directHandle,
|  | size_t | alignval
| ) |  |

inline static

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.

## SPHLFEntryDirectIncAndAlign()

static void * SPHLFEntryDirectIncAndAlign | ( | void * | directptr,
|  | size_t | incval,
|  | size_t | alignval
| ) |  |

inline static

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.

## SPHLFEntryDirectIsComplete()

static int SPHLFEntryDirectIsComplete | ( | SPHLFEntryDirect_t | directHandle | ) |

inline static

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.

## SPHLFEntryDirectIsTimestamped()

static int SPHLFEntryDirectIsTimestamped | ( | SPHLFEntryDirect_t | directHandle | ) |

inline static

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.

## SPHLFEntryDirectSubcat()

static int SPHLFEntryDirectSubcat | ( | SPHLFEntryDirect_t | directHandle | ) |

inline static

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.

## SPHSinglePCQueueAllocStrideDirect()

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

    @param queue Handle of a producer consumer queue.
    @return 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.

## SPHSinglePCQueueAllocStrideDirectSpin()

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

    @param queue Handle of a producer consumer queue.
    @return 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.

## SPHSinglePCQueueAllocStrideDirectSpinPause()

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

    @param queue Handle of a producer consumer queue.
    @return 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.

## SPHSinglePCQueueEntryIsCompleteDirect()

__C__ int SPHSinglePCQueueEntryIsCompleteDirect | ( | SPHLFEntryDirect_t | directHandle | ) |

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

    @param directHandle entry Handle for an allocated entry.
    @return true if the entry was complete (SPHSinglePCQueueEntryComplete
    has been called for this entry). Otherwise False.

## SPHSinglePCQueueFreeNextEntryDirect()

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

## SPHSinglePCQueueGetEntryTemplate()

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

## SPHSinglePCQueueGetNextCompleteDirect()

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

## SPHSinglePCQueueGetNextCompleteDirectSpin()

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

## SPHSinglePCQueueGetNextCompleteDirectSpinPause()

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

## SPHSinglePCQueueGetNextEntryDirect()

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