This header file defines the public interface for Ach. More...

#include <signal.h>
#include "ach/generic.h"

Data Structures
struct	ach_attr
	Attributes to pass to ach_open. More...

struct	ach_create_attr
	Attributes to pass to ach_create. More...

struct	ach_channel
	Descriptor for an Ach channel. More...

struct	ach_cancel_attr
	Attributes parameter for ach_cancel. More...

Macros
#define	ACH_RESTRICT
	Alias restrict keyword.

#define	ACH_DEPRECATED(msg)
	Deprecated old symbol.

Typedefs
typedef struct ach_attr	ach_attr_t
	Convenience typdedef of struct ach_attr.

typedef struct ach_create_attr	ach_create_attr_t
	Convenience typdedef of struct ach_create_attr.

typedef struct ach_channel	ach_channel_t
	Descriptor for an Ach channel. More...

typedef struct ach_cancel_attr	ach_cancel_attr_t
	Attributes parameter for ach_cancel. More...

Enumerations
enum	ach_map { ACH_MAP_DEFAULT = 0, ACH_MAP_ANON = 1, ACH_MAP_USER = 2, ACH_MAP_KERNEL = 3 }
	Options to specify the mapping for a channels backing memory buffer. More...

Functions
void	ach_attr_init (ach_attr_t *attr)
	Initialize attributes for opening channels. More...

enum ach_status ACH_WARN_UNUSED	ach_attr_set_shm (ach_attr_t attr, struct ach_header shm)
	Set shared memory area for anonymous channels.

void	ach_create_attr_init (ach_create_attr_t *attr)
	Initialize attributes for creating channels. More...

enum ach_status ACH_WARN_UNUSED	ach_create_attr_set_clock (ach_create_attr_t *attr, clockid_t clock)
	Set the clockid.

enum ach_status ACH_WARN_UNUSED	ach_create_attr_set_map (ach_create_attr_t *attr, enum ach_map map)
	Set the mapping.

enum ach_status ACH_WARN_UNUSED	ach_create_attr_set_truncate (ach_create_attr_t *attr, int truncate)
	Set to truncate.

enum ach_status ACH_WARN_UNUSED	ach_create_attr_get_shm (ach_create_attr_t attr, struct ach_header *shm)
	Get backing memory for anonymous channel.

enum ach_status ACH_WARN_UNUSED	ach_channel_fd (const struct ach_channel channel, int file_descriptor)
	Return the file descriptor associated with this channel.

enum ach_status ACH_WARN_UNUSED	ach_channel_map (const struct ach_channel channel, enum ach_map map)
	Return the mapping of the channel. More...

enum ach_status ACH_WARN_UNUSED	ach_channel_clock (const struct ach_channel channel, clockid_t clock)
	Return the clock used by the channel. More...

enum ach_status ACH_WARN_UNUSED	ach_create (const char name, size_t frame_cnt, size_t frame_size, ach_create_attr_t attr)
	Creates a new channel. More...

enum ach_status ACH_WARN_UNUSED	ach_open (ach_channel_t channel, const char name, ach_attr_t *attr)
	Opens a handle to channel. More...

enum ach_status ACH_WARN_UNUSED	ach_get (ach_channel_t chan, void buf, size_t size, size_t frame_size, const struct timespec ACH_RESTRICT abstime, int options)
	Pulls a message from the channel. More...

enum ach_status	ach_put (ach_channel_t channel, const void buf, size_t len)
	Copy a new message into the channel. More...

enum ach_status ACH_WARN_UNUSED	ach_flush (ach_channel_t *chan)
	Discards all previously received messages for this handle. More...

enum ach_status ACH_WARN_UNUSED	ach_close (ach_channel_t *chan)
	Closes the shared memory block. More...

const char *	ach_result_to_string (ach_status_t result)
	Converts return code from ach call to a human readable string;.

const char *	ach_errstr ()
	Return a string describing the most recent ach error in detail.

void	ach_dump (struct ach_header *shm)
	Prints information about the channel shm to stderr. More...

enum ach_status	ach_chmod (ach_channel_t *chan, mode_t mode)
	Sets permissions of chan to specified mode.

enum ach_status ACH_WARN_UNUSED	ach_unlink (const char *name)
	Delete an ach channel. More...

void	ach_cancel_attr_init (ach_cancel_attr_t *attr)
	Initialize attributes.

enum ach_status ACH_WARN_UNUSED	ach_cancel_attr_set_async_unsafe (ach_cancel_attr_t *attr, int asyn_unsafe)
	Set async unsafe field. More...

enum ach_status ACH_WARN_UNUSED	ach_cancel (ach_channel_t chan, const ach_cancel_attr_t attr)
	Cancel a pending ach_get() on channel.

Detailed Description

This header file defines the public interface for Ach.

Author: Neil T. Dantam

Typedef Documentation

typedef struct ach_cancel_attr ach_cancel_attr_t

Attributes parameter for ach_cancel.

Library users should access this struct through the provided functions rather than directly manipulating it.

typedef struct ach_channel ach_channel_t

Descriptor for an Ach channel.

Warning: This method may not be threadsafe. If library clients need to access the same channel from different threads, either open the channel with separate struct ach_channel desciptors for each thread, or synchronize access to the same descriptor.

Library users are strongly discourged from directly accessing members of this structure; its fields may change in future library versions. All access should be through the provided library functions.

Enumeration Type Documentation

enum ach_map

Options to specify the mapping for a channels backing memory buffer.

Enumerator
ACH_MAP_DEFAULT	Use the default mapping for channels.
ACH_MAP_ANON	anonymous channel - use heap memory
ACH_MAP_USER	Use shared memory for channels.
ACH_MAP_KERNEL	Use kernel memory for channels - requires ach kernel module to be loaded.

Function Documentation

void ach_attr_init ( ach_attr_t * attr )

Initialize attributes for opening channels.

enum ach_status ACH_WARN_UNUSED ach_cancel_attr_set_async_unsafe	(	ach_cancel_attr_t *	attr,
		int	asyn_unsafe
	)

Set async unsafe field.

enum ach_status ACH_WARN_UNUSED ach_channel_clock	(	const struct ach_channel *	channel,
		clockid_t *	clock
	)

Return the clock used by the channel.

enum ach_status ACH_WARN_UNUSED ach_channel_map	(	const struct ach_channel *	channel,
		enum ach_map *	map
	)

Return the mapping of the channel.

enum ach_status ACH_WARN_UNUSED ach_close ( ach_channel_t * chan )

Closes the shared memory block.

Precondition: chan is an initialized ach channel with open shared memory area

Postcondition: the shared memory file for chan is closed

enum ach_status ACH_WARN_UNUSED ach_create	(	const char *	name,
		size_t	frame_cnt,
		size_t	frame_size,
		ach_create_attr_t *	attr
	)

Creates a new channel.

Parameters

name	name of the channel. When requested mapping is ACH_MAP_ANON, this value is not referenced.
frame_cnt	number of frames to hold in circular buffer. Passing zero uses a default value.
frame_size	nominal size of each frame. Passing zero uses a default value.
attr	options for channel creation. Passing NULL uses default values. If channel mapping is requested as ACH_MAP_DEFAULT, ach_create() will attempt to avoid name collisions with channels of any other mapping. If an explicit mapping is requested, name collisions against other mappings are not checked.

void ach_create_attr_init ( ach_create_attr_t * attr )

Initialize attributes for creating channels.

void ach_dump ( struct ach_header * shm )

Prints information about the channel shm to stderr.

This function is mostly for internal debugging.

enum ach_status ACH_WARN_UNUSED ach_flush ( ach_channel_t * chan )

Discards all previously received messages for this handle.

Does not change the actual channel, just resets the sequence number in the handle.

enum ach_status ACH_WARN_UNUSED ach_get	(	ach_channel_t *	chan,
		void *	buf,
		size_t	size,
		size_t *	frame_size,
		const struct timespec *ACH_RESTRICT	abstime,
		int	options
	)

Pulls a message from the channel.

If a signal is delivered to a thread executing or waiting in ach_get, the thread will resume ach_get after the signal handler completes.

To interrupt a call to ach_get before a new message is received, use ach_cancel.

Precondition: chan has been opened with ach_open()

Postcondition: If buf is big enough to hold the next frame, buf contains the data for the last frame and chan.seq_num is set to the last frame. If buf is too small to hold the next frame, no side effects occur and ACH_OVERFLOW is returned. The seq_num field of chan will be set to the latest sequence number (that of the gotten frame).

Bug:: Linux kernel channels will return ACH_OK when they should return ACH_MISSED_FRAME. The data is still retrieved, but library clients are not notified of the skipped messages.

Parameters

[in,out]	chan	The previously opened channel handle
[out]	buf	Buffer to store data
[in]	size	Length of buffer in bytes
[out]	frame_size	The number of bytes copied to buf, or the size of the desired frame if buf is too small.
[in]	abstime	An absolute timeout if ACH_O_WAIT is specified. Take care that abstime is given in the correct clock. The default is defined by ACH_DEFAULT_CLOCK.
[in]	options	Option flags

Returns: On success, returns ACH_OK. Otherwise, returns an error code indication the failure:

ACH_OK: On success, returns ACH_OK and the location pointed to by frame_size contains the number of bytes copied to buf.
ACH_MISSED_FRAME: If any frames were skipped in the buffer, the ACH_MISSED_FRAME may be returned. The data is still copied and frame_size set as on ACH_OK.
ACH_STALE_FRAMES
ACH_TIMEOUT
ACH_CANCELED
ACH_OVERFLOW
ACH_CORRUPT
ACH_EINVAL
ACH_EFAULT

See Also: ach_get_opts_t, ach_status

enum ach_status ACH_WARN_UNUSED ach_open	(	ach_channel_t *	channel,
		const char *	name,
		ach_attr_t *	attr
	)

Opens a handle to channel.

Postcondition: A file descriptor for the named channel is opened, and channel is initialized.

Parameters

channel	pointer to an unitialized or previously closed channel struct
name	The name of the channel. If mapping requested ACH_MAP_ANON, this value is not referenced.
attr	options for channel opening. If mapping requested ACH_MAP_DEFAULT, check all available mappings for channel of the passed name.

Returns: ACH_OK on success. Otherwise, return an error code indicating the particular error.

enum ach_status ach_put	(	ach_channel_t *	channel,
		const void *	buf,
		size_t	len
	)

Copy a new message into the channel.

Precondition: chan has been opened with ach_open() and is large enough to hold the message.

Postcondition: The contents of buf are copied into the channel and the sequence number of the channel is incremented. If the channel is too small to hold the message, the message is not copied into the channel as will not be seen by receivers.

Parameters

[in,out]	channel	The channel to write to
[in]	buf	the buffer containing the data to copy into the channel
[in]	len	number of bytes in buf to copy, len > 0

Returns: ACH_OK on success. If the channel is too small to hold the frame, returns ACH_OVERFLOW.

enum ach_status ACH_WARN_UNUSED ach_unlink ( const char * name )

Delete an ach channel.

Remove the channel from all underlying mappings.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation