IEEE Robotics & Automation Magazine - March 2015 - 79

The Ach IPC Library
Ach provides a message bus or publish-subscribe style of
communication between multiple writers and multiple
readers. A real-time system has multiple Ach channels
across which individual data samples are published. Messages are sent as byte arrays, so arbitrary data may be transmitted, such as floating point vectors, text, images, and
binary control messages. Each channel is implemented as
two circular buffers: 1) a data buffer with variable-sized
entries and 2) an index buffer with fixed-size elements indicating the offsets into the data buffer. These two circular
buffers are written in a channel-specific POSIX shared
memory file. Using this formulation, we solve and formally
verify the synchronization problem exactly once and contain it entirely within the Ach library.
The Ach interface consists of the following procedures.
● ach_create: Create the shared memory region and initialize its data structures.
● ach_open: Open the shared memory file and initialize
process local channel counters.
● ach_put: Insert a new message into the channel.
● ach_get: Receive a message from the channel.
● ach_close: Close the shared memory file.
Channels must be created before they can be opened. Creation
may be done directly by either the reading or writing process,
or it may be done via the shell command, ach mk channel_
name, before the reader or writer start. This is analogous to the
creation of FIFOs with either the mkfifo shell command or
C function. After the channel is created, each reader or writer
must open the channel before it can get or put messages.
Channel Data Structure
The core data structure of an Ach channel is a pair of circular arrays located in the POSIX shared memory file (Figure 2). It differs from typical circular buffers by permitting
multiple consumers to access the same message from the
channel. The data array contains variable-sized elements
that store the actual message frames sent through the Ach
channel. The index array contains fixed-size elements
where each element contains both an offset into the data
array and the length of that data element. A head offset into
each array indicates the place to insert the next data and the
location of the most recent message frame. Each reader
maintains its own offset into the index array, indicating the
last message seen by that reader. This pair of circular arrays
allows readers to find the variable-size message frames
based on the index array offset and the corresponding
entry in the data array.
Access to the channel is synchronized using a mutex and
condition variable. This allows readers to either periodically
poll the channel for new data or wait on the condition variable until a writer has posted a new message. Using a read/
write lock instead would have allowed only polling. In addition, synchronization using a mutex prevents starvation and
enables proper priority inheritance between processes, which
is important to maintaining real-time performance.

2
header

index_head index _free data_head data_free

index_array

data_array

Figure 2. A logical memory structure for an Ach shared memory
file. In this example, I 0 points to a 4-byte message starting at
D 1, and I 1 points to a 1-byte message starting at D 5 . The next
inserted message will use index cell I 2 and start at D 6 . There
are two free index cells and three free data bytes. Both arrays are
circular and wrap around when the end is reached.

Core Procedures
Two procedures compose the core of Ach: ach_put and
ach_get. Detailed pseudocode is provided in [6].
ach_put
The procedure ach_put inserts new messages into the
channel. It is analogous to write, sendmsg, and mq_send.
The procedure is given a pointer to the shared memory
region for the channel and a byte array containing the message to post. There are four broad steps to the procedure.
1) Get an index entry. If there is at least one free index entry,
use it. Otherwise, clear the oldest index entry and its corresponding message in the data array.
2) Make room in the data array. If there is enough room
already, continue. Otherwise, repeatedly free the oldest
message until there is enough room.
3) Copy the message into data array.
4) Update the offset and free counts in the channel structure.
ach_get
The procedure ach_get receives a message from the channel. It is analogous to read, recvmsg, and mq_receive.
The procedure takes a pointer to the shared memory region, a
storage buffer to copy the message to, the last message
sequence number received, the next index offset to check for
a message, and option flags indicating whether to block waiting for a new message and whether to return the newest message bypassing any older unseen messages. There are four
broad steps to the procedure.
1) If we are to wait for a new message and there is no new
message, then wait. Otherwise, if there are no new messages, return a status code indicating this fact.
2) Find the index entry to use. If we are to return the newest
message, use that entry. Otherwise, if the next entry we
expected to use contains the next sequence number we
expect to see, use that entry. Otherwise, use the oldest entry.
March 2015

IEEE ROBOTICS & AUTOMATION MAGAZINE

Table of Contents for the Digital Edition of IEEE Robotics & Automation Magazine - March 2015