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?
int32_t	qb_ipcc_get_buffer_size (qb_ipcc_connection_t *c)
	What is the actual buffer size used after the connection.

---

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

Examples:

ipcclient.c.

---

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_get_buffer_size

(

qb_ipcc_connection_t *

c

)

What is the actual buffer size used after the connection.

Note:

The buffer size is guaranteed to be at least the size of the value given in qb_ipcc_connect, but it is possible the server will enforce a larger size depending on the implementation. If the server side is known to enforce a buffer size, use this function after the client connection is established to retrieve the buffer size in use. It is important for the client side to know the buffer size in use so the client can successfully retrieve large server events.

Parameters:

c

connection instance

Return values:

connection

size in bytes or -error code

Examples:

ipcclient.c.

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.