Programming with Direct Publishers

Create a direct publisher object. Code a reserve-fill-send loop. Close the direct publisher and exit.

Number of Publisher Objects

A suite of application processes that communicate over a direct shared memory bus may contain only one direct publisher object at a time. It is the shared responsibility of the application developers and the administrators to ensure this condition.

One Reserved Buffer

A direct publisher can reserve at most one buffer at a time.

  • If direct publisher has already reserved a buffer in one thread, any subsequent reserve calls in other threads block until the direct publisher has sent the reserved buffer.
  • Do not call reserve twice within the same thread without an intervening send call.

The Reserve-Fill-Send Loop

Avoid delays in the reserve-fill-send loop: as soon as the reserve call returns a buffer, fill it with data, and send it.

    Procedure
  1. Create a direct publisher object.
    The object will exist in memory until the process terminates.
    Programs may use a direct publisher in multiple threads. However, contention to reserve a buffer can decrease performance and increase latency.
    2. The reserve-fill-send loop begins here.
  2. Reserve a buffer.
    Supply the total size of the data, and the number of data elements.
     
    The reserve call returns a pointer to the buffer.

    If the program specifies more than one data element, the reserve call also yield a size array.

    Note: One reserve call can reserve a maximum block of 64 kilobytes. The data buffer and the size array must fit together within that maximum block.
  3. Fill the buffer with data.
    If another thread has already reserved a buffer with this direct publisher, this reserve call blocks until that other thread sends its buffer.
    One Data Element: Write the data into the buffer.
    Multiple Data Elements: Use a loop to write each data element into the buffer, and its corresponding size, in bytes, into the size array.
  4. Send the reserved buffer.
    The send reserved call makes the buffer available to direct subscribers.

    After this call, the direct publisher is ready to reserve another buffer.

  5. Loop to reserve the next buffer.
    6. Clean up before the application process exits.
  6. Close the direct publisher object.
    Closing a direct publisher causes any blocked reserve calls to return. Closing also invalidates the direct publisher, which disallows any subsequent method calls.

    However, closing a direct publisher does not free its memory.