ipc.h File Reference

Go to the source code of this file.

Data Structures
struct	a_ipc_msg_info
	IPC message basic info. More...

Macros
#define	A_IPC_ALLOC_MSG_BUFFER(name, size, modifiers)
	Helper macro to allocate space for a message structure NOTE, never use this directly, use A_IPC_MSG_ON_STACK or A_IPC_STATIC_MSG.
#define	A_IPC_MSG_ON_STACK(name, size)
	Allocate a message buffer on the stack. More...
#define	A_IPC_STATIC_MSG(name, size)
	Allocate a message buffer statically. More...
#define	A_IPC_STATIC_BUFFERS(name, inbox_size, outbox_size)
	Allocate ipc inbox/outbox buffers statically. More...
#define	A_IPC_STATIC_BUFFERS_BYTES(name, inbox_size, outbox_size)
	Allocate ipc inbox/outbox buffers statically. More...
#define	A_IPC_ALLOCATE_BUFFERS(name, inbox_size, outbox_size)
	Allocate ipc inbox/outbox buffers dynamically. More...
#define	A_IPC_ALLOCATE_BUFFERS_BYTES(name, inbox_size, outbox_size)
	Allocate ipc inbox/outbox buffers dynamically. More...
#define	A_IPC_GUEST_MIN_ID
	Minimum allowed IPC ID for User VM applications.
#define	A_IPC_GUEST_MAX_ID
	Maximum allowed IPC ID for User VM applications.

Typedefs
typedef struct a_ipc_buffers	a_ipc_buffers
	Handle to a struct containing IPC inbox/outbox buffers.
typedef struct a_ipc_handle	a_ipc_handle
	Handle to an IPC instance. More...

Enumerations
enum	A_IPC_RESULT {   A_IPC_RET_OK , A_IPC_RET_ERROR , A_IPC_RET_BUFFER_TOO_SMALL , A_IPC_RET_BAD_TYPE ,   A_IPC_RET_NO_MSG , A_IPC_RET_SEND_ERROR , A_IPC_RET_TIMEOUT , A_IPC_RET_MALFORMED_PACKET ,   A_IPC_RET_NOT_IMPLEMENTED , A_IPC_RET_OUT_OF_MEMORY , A_IPC_RET_INVALID_ARGUMENT , A_IPC_RET_OUTBOX_FULL }
	IPC function result codes. More...

Functions
a_ipc_handle *	a_ipc_init (int id, a_ipc_buffers *buffers)
	Initialize AIPC and make application available to other IPC applications. More...
a_ipc_handle *	a_ipc_init_ex (int id, a_ipc_buffers *buffers, unsigned int outstanding_window)
	Initialize AIPC and make application available to other IPC applications. More...
void	a_ipc_destroy (a_ipc_handle *handle)
	Destroy AIPC. More...
void	a_ipc_free_buffers (a_ipc_buffers *buffers)
	Free the memory of a dynamically alloctated ipc inbox/outbox buffers struct. More...
int	a_ipc_get_fd (a_ipc_handle *handle)
	Get file descriptor for selecting/polling for new messages. More...
A_IPC_RESULT	a_ipc_send (a_ipc_handle *handle, int to, a_ipc_msg *msg)
	Send an IPC message. More...
A_IPC_RESULT	a_ipc_recv (a_ipc_handle *handle, int *from, a_ipc_msg *msg)
	Receive an IPC message. More...
A_IPC_RESULT	a_ipc_copy_message (a_ipc_msg *dst, const a_ipc_msg *src)
	Copy an IPC message. More...
const char *	a_ipc_msg_type_str (int msg_type)
	Get the string representation (enum constant) for the given msg_type. More...
const char *	a_ipc_result_str (A_IPC_RESULT result)
	Get the string representation for the given result value. More...
int	a_ipc_dump_stats (a_ipc_handle *handle)
	Outputs information to the log about the current IPC instance. More...

---

Data Structure Documentation

a_ipc_msg_info

struct a_ipc_msg_info

IPC message basic info.

These members should not be updated by the user.

Data Fields
size_t	msg_alloc_size	Total message size - including struct members.
size_t	msg_used_size	How much of the message that is used - including struct members.
int	type	The message type, as given by the user-provided IPC IDs file.

Macro Definition Documentation

A_IPC_ALLOCATE_BUFFERS

#define A_IPC_ALLOCATE_BUFFERS	(		name,
			inbox_size,
			outbox_size
	)

Allocate ipc inbox/outbox buffers dynamically.

DEPRECATED This is a legacy helper and has been replaced by A_IPC_ALLOCATE_BUFFERS_BYTES

Prefer the static macro for better memory utilization.

The resulting variable is equivalent to

a_ipc_buffers *name;

Note: The macro expands to multiple lines.

Parameters

name	Name of the variable
inbox_size	Size of the inbox buffer, in number of messages.
outbox_size	Size of the outbox buffer, in number of messages.

A_IPC_ALLOCATE_BUFFERS_BYTES

#define A_IPC_ALLOCATE_BUFFERS_BYTES	(		name,
			inbox_size,
			outbox_size
	)

Allocate ipc inbox/outbox buffers dynamically.

Prefer the static macro for better memory utilization.

The resulting variable is equivalent to

a_ipc_buffers *name;

Note: The macro expands to multiple lines.

Parameters

name	Name of the variable
inbox_size	Size of the inbox buffer, in bytes.
outbox_size	Size of the outbox buffer, in bytes.

A_IPC_MSG_ON_STACK

#define A_IPC_MSG_ON_STACK	(		name,
			size
	)

Allocate a message buffer on the stack.

The resulting variable is equivalent to

a_ipc_msg *name;

Note: The macro expands to multiple lines.

Note: This can be used both on function scope and file scope.

Parameters

name	Name of the variable
size	Size of the buffer, in bytes.

A_IPC_STATIC_BUFFERS

#define A_IPC_STATIC_BUFFERS	(		name,
			inbox_size,
			outbox_size
	)

Allocate ipc inbox/outbox buffers statically.

DEPRECATED This is a legacy helper and has been replaced by A_IPC_STATIC_BUFFERS_BYTES. Each buffer will be sized as 512 * number of messages

Typically placed at the top of a code file.

The resulting variable is equivalent to

static a_ipc_buffers name;

Note: The macro expands to multiple lines.

Parameters

name	Name of the variable
inbox_size	Size of the inbox buffer, in number of messages.
outbox_size	Size of the outbox buffer, in number of messages.

A_IPC_STATIC_BUFFERS_BYTES

#define A_IPC_STATIC_BUFFERS_BYTES	(		name,
			inbox_size,
			outbox_size
	)

Allocate ipc inbox/outbox buffers statically.

Typically placed at the top of a code file.

The resulting variable is equivalent to

static a_ipc_buffers name;

Note: The macro expands to multiple lines.

Parameters

name	Name of the variable
inbox_size	Size of the inbox buffer, in bytes
outbox_size	Size of the outbox buffer, in bytes.

A_IPC_STATIC_MSG

#define A_IPC_STATIC_MSG	(		name,
			size
	)

Allocate a message buffer statically.

The resulting variable is equivalent to

static a_ipc_msg *name;

Note: The macro expands to multiple lines.

Note: This can be used both on function scope and file scope.

Parameters

name	Name of the variable
size	Size of the buffer, in bytes.

Typedef Documentation

a_ipc_handle

typedef struct a_ipc_handle a_ipc_handle

Handle to an IPC instance.

Created with a_ipc_init().

Enumeration Type Documentation

A_IPC_RESULT

enum A_IPC_RESULT

IPC function result codes.

Enumerator
A_IPC_RET_OK	Operation succeeded.
A_IPC_RET_ERROR	Unspecified error.
A_IPC_RET_BUFFER_TOO_SMALL	The provided buffer is too small.
A_IPC_RET_BAD_TYPE	The message type is not known.
A_IPC_RET_NO_MSG	No message found/received.
A_IPC_RET_SEND_ERROR	Error when signaling message to be sent.
A_IPC_RET_TIMEOUT	Timeout while waiting.
A_IPC_RET_MALFORMED_PACKET	Malformed packet in transport layer.
A_IPC_RET_NOT_IMPLEMENTED	Functionality not implemented.
A_IPC_RET_OUT_OF_MEMORY	Not enough memory (allocated) to perform the request action.
A_IPC_RET_INVALID_ARGUMENT	Invalid arguments given.
A_IPC_RET_OUTBOX_FULL	Outbox full.

Function Documentation

a_ipc_copy_message()

A_IPC_RESULT a_ipc_copy_message	(	a_ipc_msg *	dst,
		const a_ipc_msg *	src
	)

Copy an IPC message.

Both buffers must have been initialized.

Parameters

dst	Message buffer to copy to.
src	Message buffer to copy from.

Returns

A_IPC_RET_OK on success. Otherwise an A_IPC_RESULT.

a_ipc_destroy()

void a_ipc_destroy

(

a_ipc_handle *

handle

)

Destroy AIPC.

Clears up used resources and makes the application unavailable to other IPC applications.

Parameters

handle

AIPC handle.

a_ipc_dump_stats()

int a_ipc_dump_stats

(

a_ipc_handle *

handle

)

Outputs information to the log about the current IPC instance.

Includes: Max slot usage of inbox and outbox

Parameters

handle

AIPC handle

Returns

A_IPC_RET_OK on success. Otherwise an A_IPC_RESULT.

a_ipc_free_buffers()

void a_ipc_free_buffers

(

a_ipc_buffers *

buffers

)

Free the memory of a dynamically alloctated ipc inbox/outbox buffers struct.

Parameters

buffers

inbox/outbox buffers.

a_ipc_get_fd()

int a_ipc_get_fd

(

a_ipc_handle *

handle

)

Get file descriptor for selecting/polling for new messages.

Use a_ipc_recv() to receive the messages.

Parameters

handle

AIPC handle.

Returns

A file descriptor, or -1 on error.

a_ipc_init()

a_ipc_handle* a_ipc_init	(	int	id,
		a_ipc_buffers *	buffers
	)

Initialize AIPC and make application available to other IPC applications.

Messages can arrive after initializing.

This version will use defaults or heuristics to determine additional settings.

Note: This function potentially starts threads, if you need to block signals for e.g. signalfd(2), make sure to do so before calling this function.

Parameters

id	Unique ID of the endpoint.
buffers	Struct containing inbox and outbox buffers. Use A_IPC_ALLOCATE_BUFFERS_BYTES to allocate dynamically, or use A_IPC_STATIC_BUFFERS_BYTES to allocate statically.

Returns

Handle to AIPC, or NULL on error.

a_ipc_init_ex()

a_ipc_handle* a_ipc_init_ex	(	int	id,
		a_ipc_buffers *	buffers,
		unsigned int	outstanding_window
	)

Initialize AIPC and make application available to other IPC applications.

Messages can arrive after initializing.

This version allows to specify additional settings compared to a_ipc_init.

Note: This function potentially starts threads, if you need to block signals for e.g. signalfd(2), make sure to do so before calling this function.

Parameters

id	Unique ID of the endpoint.
buffers	Struct containing inbox and outbox buffers. Use A_IPC_ALLOCATE_BUFFERS_BYTES to allocate dynamically, or use A_IPC_STATIC_BUFFERS_BYTES to allocate statically.
outstanding_window	The number of messages that can be in-flight at any time that has not been ACKed by the receiver.

Returns

Handle to AIPC, or NULL on error.

a_ipc_msg_type_str()

const char* a_ipc_msg_type_str

(

int

msg_type

)

Get the string representation (enum constant) for the given msg_type.

Parameters

msg_type

Message type (A_IPC_MSG_*)

Returns

String representation of the message type or "Unknown (<ID>)".

a_ipc_recv()

A_IPC_RESULT a_ipc_recv	(	a_ipc_handle *	handle,
		int *	from,
		a_ipc_msg *	msg
	)

Receive an IPC message.

The contents of msg are undefined if the return value is not A_IPC_RET_OK or A_IPC_RET_SEND_ERROR.

Parameters

handle	AIPC handle.
from	Populated with ID of the sender. This argument can be NULL, if the value is not of interest.
msg	Message buffer for the received message.

Returns

• A_IPC_RET_OK on success.
• A_IPC_RET_NO_MSG when no message was received.
• A_IPC_RET_SEND_ERROR when a previous a_ipc_send() has failed. In this case the returned message type is an ipc_send_error_ind.
• Otherwise an A_IPC_RESULT.

a_ipc_result_str()

const char* a_ipc_result_str

(

A_IPC_RESULT

result

)

Get the string representation for the given result value.

Parameters

result

Result

Returns

String representation of the result or "Unknown (<ID>)".

a_ipc_send()

A_IPC_RESULT a_ipc_send	(	a_ipc_handle *	handle,
		int	to,
		a_ipc_msg *	msg
	)

Send an IPC message.

Parameters

handle	AIPC handle.
to	ID of the receiver.
msg	Initialized and filled-in message to send.

Returns

• A_IPC_RET_OK on success.
• A_IPC_RET_OUT_OF_MEMORY when the message is too large.
• A_IPC_RET_OUTBOX_FULL when the outbox is full.
• Otherwise an A_IPC_RESULT.