qbipcc.h File Reference

Client IPC API. More...

#include <qb/qbconfig.h>
#include <pthread.h>
#include <sys/poll.h>
#include <sys/socket.h>
#include <qb/qbhdb.h>
#include <qb/qbipc_common.h>

Include dependency graph for qbipcc.h:

Typedefs
typedef struct qb_ipcc_connection	qb_ipcc_connection_t

Functions
qb_ipcc_connection_t *	qb_ipcc_connect (const char *name, size_t max_msg_size)
	Create a connection to an IPC service.
int32_t	qb_ipcc_verify_dgram_max_msg_size (size_t max_msg_size)
	Test kernel dgram socket buffers to verify the largest size up to the max_msg_size value a single msg can be.
void	qb_ipcc_disconnect (qb_ipcc_connection_t *c)
	Disconnect an IPC connection.
int32_t	qb_ipcc_fd_get (qb_ipcc_connection_t *c, int32_t *fd)
	Get the file descriptor to poll.
int32_t	qb_ipcc_fc_enable_max_set (qb_ipcc_connection_t *c, uint32_t max)
	Set the maximum allowable flowcontrol value.
ssize_t	qb_ipcc_send (qb_ipcc_connection_t *c, const void *msg_ptr, size_t msg_len)
	Send a message.
ssize_t	qb_ipcc_sendv (qb_ipcc_connection_t *c, const struct iovec *iov, size_t iov_len)
	Send a message (iovec).
ssize_t	qb_ipcc_recv (qb_ipcc_connection_t *c, void *msg_ptr, size_t msg_len, int32_t ms_timeout)
	Receive a response.
ssize_t	qb_ipcc_sendv_recv (qb_ipcc_connection_t *c, const struct iovec *iov, uint32_t iov_len, void *msg_ptr, size_t msg_len, int32_t ms_timeout)
	This is a convenience function that simply sends and then recvs.
ssize_t	qb_ipcc_event_recv (qb_ipcc_connection_t *c, void *msg_ptr, size_t msg_len, int32_t ms_timeout)
	Receive an event.
void	qb_ipcc_context_set (qb_ipcc_connection_t *c, void *context)
	Associate a "user" pointer with this connection.
void *	qb_ipcc_context_get (qb_ipcc_connection_t *c)
	Get the context (set previously)
int32_t	qb_ipcc_is_connected (qb_ipcc_connection_t *c)
	Is the connection connected?

Detailed Description

Client IPC API.

Lifecycle of an IPC connection.

An IPC connection is made to the server with qb_ipcc_connect(). This function connects to the server and requests channels be created for communication. To disconnect, the client either exits or executes the function qb_ipcc_disconnect().

Synchronous communication

The function qb_ipcc_sendv_recv() sends an iovector request and receives a response.

Asynchronous requests from the client

The function qb_ipcc_sendv() sends an iovector request. The function qb_ipcc_send() sends an message buffer request.

Asynchronous events from the server

The qb_ipcc_event_recv() function receives an out-of-band asyncronous message. The asynchronous messages are queued and can provide very high out-of-band performance. To determine when to call qb_ipcc_event_recv() the qb_ipcc_fd_get() call is used to obtain a file descriptor used in the poll() or select() system calls.

Typedef Documentation

typedef struct qb_ipcc_connection qb_ipcc_connection_t

Function Documentation

qb_ipcc_connection_t* qb_ipcc_connect	(	const char *	name,
		size_t	max_msg_size
	)

Create a connection to an IPC service.

Parameters

name	name of the service.
max_msg_size	biggest msg size.

Returns

NULL (error: see errno) or a connection object.

Note

It is recommended to do a one time check on the max_msg_size value using qb_ipcc_verify_dgram_max_msg_size BEFORE calling the connect function when IPC_SOCKET is in use. Some distributions while allow large message buffers to be set on the socket, but not actually honor them because of kernel state values. The qb_ipcc_verify_dgram_max_msg_size function both sets the socket buffer size and verifies it by doing a send/recv.

Examples:

ipcclient.c.

void* qb_ipcc_context_get

(

qb_ipcc_connection_t *

c

)

Get the context (set previously)

Parameters

c	connection instance

Returns

the context

See Also

qb_ipcc_context_set()

void qb_ipcc_context_set	(	qb_ipcc_connection_t *	c,
		void *	context
	)

Associate a "user" pointer with this connection.

Parameters

context	the point to associate with this connection.
c	connection instance

See Also

qb_ipcc_context_get()

void qb_ipcc_disconnect

(

qb_ipcc_connection_t *

c

)

Disconnect an IPC connection.

Parameters

c	connection instance

Examples:

ipcclient.c.

ssize_t qb_ipcc_event_recv	(	qb_ipcc_connection_t *	c,
		void *	msg_ptr,
		size_t	msg_len,
		int32_t	ms_timeout
	)

Receive an event.

Parameters

c	connection instance
msg_ptr	pointer to a message buffer to receive into
msg_len	the size of the buffer
ms_timeout	time in milli seconds to wait for a message 0 == no wait, negative == block, positive == wait X ms.
ms_timeout	max time to wait for a response

Returns

size of the message or error (-errno)

Note

that msg_ptr will include a qb_ipc_response_header at the top of the message.

Examples:

ipcclient.c.

int32_t qb_ipcc_fc_enable_max_set	(	qb_ipcc_connection_t *	c,
		uint32_t	max
	)

Set the maximum allowable flowcontrol value.

Note

the default is 1

Parameters

c	connection instance
max	the max allowable flowcontrol value (1 or 2)

int32_t qb_ipcc_fd_get	(	qb_ipcc_connection_t *	c,
		int32_t *	fd
	)

Get the file descriptor to poll.

Parameters

c	connection instance
fd	(out) file descriptor to poll

int32_t qb_ipcc_is_connected

(

qb_ipcc_connection_t *

c

)

Is the connection connected?

Parameters

c	connection instance

Return values

QB_TRUE	when connected
QB_FALSE	when not connected

ssize_t qb_ipcc_recv	(	qb_ipcc_connection_t *	c,
		void *	msg_ptr,
		size_t	msg_len,
		int32_t	ms_timeout
	)

Receive a response.

Parameters

c	connection instance
msg_ptr	pointer to a message buffer to receive into
msg_len	the size of the buffer
ms_timeout	max time to wait for a response

Returns

(size recv'ed, -errno == error)

Note

that msg_ptr will include a qb_ipc_response_header at the top of the message.

Examples:

ipcclient.c.

ssize_t qb_ipcc_send	(	qb_ipcc_connection_t *	c,
		const void *	msg_ptr,
		size_t	msg_len
	)

Send a message.

Parameters

c	connection instance
msg_ptr	pointer to a message to send
msg_len	the size of the message

Returns

(size sent, -errno == error)

Note

the msg_ptr must include a qb_ipc_request_header at the top of the message. The server will read the size field to determine how much to recv.

Examples:

ipcclient.c.

ssize_t qb_ipcc_sendv	(	qb_ipcc_connection_t *	c,
		const struct iovec *	iov,
		size_t	iov_len
	)

Send a message (iovec).

Parameters

c	connection instance
iov	pointer to an iovec struct to send
iov_len	the number of iovecs used

Returns

(size sent, -errno == error)

Note

the iov[0] must be a qb_ipc_request_header. The server will read the size field to determine how much to recv.

Examples:

ipcclient.c.

ssize_t qb_ipcc_sendv_recv	(	qb_ipcc_connection_t *	c,
		const struct iovec *	iov,
		uint32_t	iov_len,
		void *	msg_ptr,
		size_t	msg_len,
		int32_t	ms_timeout
	)

This is a convenience function that simply sends and then recvs.

Parameters

c	connection instance
iov	pointer to an iovec struct to send
iov_len	the number of iovecs used
msg_ptr	pointer to a message buffer to receive into
msg_len	the size of the buffer
ms_timeout	max time to wait for a response

Note

the iov[0] must include a qb_ipc_request_header at the top of the message. The server will read the size field to determine how much to recv.

that msg_ptr will include a qb_ipc_response_header at the top of the message.

See Also

qb_ipcc_sendv() qb_ipcc_recv()

int32_t qb_ipcc_verify_dgram_max_msg_size

(

size_t

max_msg_size

)

Test kernel dgram socket buffers to verify the largest size up to the max_msg_size value a single msg can be.

Rounds down to the nearest 1k.

Parameters

max_msg_size

biggest msg size.

Returns

-1 if max size can not be detected, positive value representing the largest single msg up to max_msg_size that can successfully be sent over a unix dgram socket.