Initialization and Teardown
[Protocol-Independent API]

---

Detailed Description

miniRPC maintains the notion of a connection set, which is a group of connections sharing common configuration and infrastructure. A connection set includes the following:

• A background thread which handles network I/O for the associated connections. This thread is started when the connection set is created, and stopped when it is destroyed.
• A protocol role
• Configuration parameters, such as the maximum message size
• Callback functions for notification of events such as a newly-accepted connection or a connection shutdown

An application can create as many connection sets as it wishes, but most applications will need only one. In most cases, all connections with the same protocol role can be placed into the same connection set.

Defines
#define	MRPC_VERSION_CODE()
	Get the version code for the miniRPC headers the application was compiled against.
#define	MRPC_MAKE_VERSION_CODE(major, minor, revision)
	Make a version code from the specified components.
#define	MRPC_VERSION_MAJOR(code)
	Extract a major version number from a version code.
#define	MRPC_VERSION_MINOR(code)
	Extract a minor version number from a version code.
#define	MRPC_VERSION_REVISION(code)
	Extract a revision number from a version code.
Functions
int	mrpc_version_code (void)
	Get the version code for the miniRPC library the application is running against.
int	mrpc_conn_set_create (struct mrpc_conn_set **new_set, const struct mrpc_protocol *protocol, void *set_data)
	Create a connection set.
void	mrpc_conn_set_ref (struct mrpc_conn_set *set)
	Increment the refcount of a connection set.
void	mrpc_conn_set_unref (struct mrpc_conn_set *set)
	Decrement the refcount of a connection set.
int	mrpc_set_accept_func (struct mrpc_conn_set *set, mrpc_accept_fn *func)
	Set the function to be called when a new connection arrives on a listening socket.
int	mrpc_set_disconnect_func (struct mrpc_conn_set *set, mrpc_disconnect_fn *func)
	Set the function to be called when a connection is closed for any reason.
int	mrpc_set_ioerr_func (struct mrpc_conn_set *set, mrpc_ioerr_fn *func)
	Set the function to be called when a connection encounters an I/O error.
int	mrpc_set_max_buf_len (struct mrpc_conn_set *set, unsigned len)
	Set the maximum length of a received message payload.
int	mrpc_set_listen_backlog (struct mrpc_conn_set *set, unsigned backlog)
	Set the number of accepted connections that can be waiting in the kernel.
int	mrpc_set_accept_backoff (struct mrpc_conn_set *set, unsigned ms)
	Set the number of milliseconds to back off if accept() fails.
int	mrpc_set_keepalive_enabled (struct mrpc_conn_set *set, int enabled)
	Set whether keepalives will be enabled on new connections.
int	mrpc_set_keepalive_parameters (struct mrpc_conn_set *set, unsigned idletime, unsigned count, unsigned interval)
	Set TCP keepalive parameters for new connections.

---

Define Documentation

 

#define MRPC_VERSION_CODE

(

)

Get the version code for the miniRPC headers the application was compiled against.

Returns:

The version code

Version codes for higher versions are numerically greater than version codes for lower versions.

#define MRPC_MAKE_VERSION_CODE	(	major,
		minor,
		revision		)

Make a version code from the specified components.

Parameters:

	major	The major release number
	minor	The minor release number
	revision	The revision number

Version codes for higher versions are numerically greater than version codes for lower versions.

#define MRPC_VERSION_MAJOR

(

code

)

Extract a major version number from a version code.

Parameters:

code

The version code

Returns:

The major version number

#define MRPC_VERSION_MINOR

(

code

)

Extract a minor version number from a version code.

Parameters:

code

The version code

Returns:

The minor version number

#define MRPC_VERSION_REVISION

(

code

)

Extract a revision number from a version code.

Parameters:

code

The version code

Returns:

The revision number

---

Function Documentation

int mrpc_version_code

(

void

)

Get the version code for the miniRPC library the application is running against.

Returns:

The version code

Version codes for higher versions are numerically greater than version codes for lower versions.

int mrpc_conn_set_create	(	struct mrpc_conn_set **	new_set,
		const struct mrpc_protocol *	protocol,
		void *	set_data
	)

Create a connection set.

Parameters:

[out]	new_set	The resulting connection set, or NULL on error
	protocol	Protocol role definition for connections in this connection set
	set_data	An application-specific cookie for this connection set

Returns:

A POSIX error code, or 0 on success

Create a connection set with a refcount of 1, associate it with the specified protocol role and application-specific pointer, start its background thread, and return a handle to the connection set. If set_data is NULL, set the application-specific pointer to the connection set handle returned in new_set.

void mrpc_conn_set_ref

(

struct mrpc_conn_set *

set

)

Increment the refcount of a connection set.

Parameters:

set

The connection set

Get an additional reference to the specified connection set.

Note:

Dispatcher threads should not hold their own persistent references to the set for which they are dispatching.

void mrpc_conn_set_unref

(

struct mrpc_conn_set *

set

)

Decrement the refcount of a connection set.

Parameters:

set

The connection set

Put a reference to the specified connection set. When the refcount reaches zero and there are no connections or listening sockets associated with the set, the set will be destroyed. Destruction of a connection set involves the following steps:

1. Shut down all threads started with mrpc_start_dispatch_thread(), and cause all other dispatch functions to return ENXIO
2. Wait for dispatching threads to call mrpc_dispatcher_remove()
3. Shut down the background thread associated with the connection set
4. Free the set's data structures

After the set's refcount reaches zero, the application must not start any additional dispatchers or create any connections against the set. However, if the set still has listening sockets, new connections may continue to arrive. In addition, the application should continue to dispatch events against the set (if it is doing its own dispatching) until the dispatcher functions return ENXIO.

int mrpc_set_accept_func	(	struct mrpc_conn_set *	set,
		mrpc_accept_fn *	func
	)

Set the function to be called when a new connection arrives on a listening socket.

Parameters:

	set	The connection set to configure
	func	The accept function

Returns:

A POSIX error code, or 0 on success

See also:

mrpc_accept_fn

The application must set an accept function before calling mrpc_listen() on set.

int mrpc_set_disconnect_func	(	struct mrpc_conn_set *	set,
		mrpc_disconnect_fn *	func
	)

Set the function to be called when a connection is closed for any reason.

Parameters:

	set	The connection set to configure
	func	The disconnect function, or NULL for none

Returns:

A POSIX error code, or 0 on success

See also:

mrpc_disconnect_fn

By default, no disconnect function is provided.

int mrpc_set_ioerr_func	(	struct mrpc_conn_set *	set,
		mrpc_ioerr_fn *	func
	)

Set the function to be called when a connection encounters an I/O error.

Parameters:

	set	The connection set to configure
	func	The ioerr function, or NULL for none

Returns:

A POSIX error code, or 0 on success

See also:

mrpc_ioerr_fn

By default, no ioerr function is provided.

int mrpc_set_max_buf_len	(	struct mrpc_conn_set *	set,
		unsigned	len
	)

Set the maximum length of a received message payload.

Parameters:

	set	The connection set to configure
	len	The maximum payload length in bytes. Must be greater than zero.

Returns:

A POSIX error code, or 0 on success

Set the maximum length, in bytes, of an XDR-encoded message received from the remote system. The default value is 16384. Requests exceeding this threshold will be rejected and MINIRPC_ENCODING_ERR will be returned to the sender. Replies exceeding this threshold will be treated as though the remote system returned MINIRPC_ENCODING_ERR. Unidirectional messages exceeding the threshold will be dropped.

This is intended only as a denial-of-service prevention measure, and should be set to a value larger than any legitimate message possible in your protocol.

int mrpc_set_listen_backlog	(	struct mrpc_conn_set *	set,
		unsigned	backlog
	)

Set the number of accepted connections that can be waiting in the kernel.

Parameters:

	set	The connection set to configure
	backlog	The length of the backlog queue. Must be greater than zero.

Returns:

A POSIX error code, or 0 on success

Set the maximum number of connections that can be queued in the kernel waiting for accept(); this corresponds to the backlog parameter to the listen() system call. The default value is 16. The new setting will only affect future calls to mrpc_listen(); existing listening sockets will not be affected.

int mrpc_set_accept_backoff	(	struct mrpc_conn_set *	set,
		unsigned	ms
	)

Set the number of milliseconds to back off if accept() fails.

Parameters:

	set	The connection set to configure
	ms	The number of milliseconds to wait. Must be greater than zero.

Returns:

A POSIX error code, or 0 on success

If an error occurs while accepting a connection on a listening socket, miniRPC will wait this many milliseconds before trying to accept any more connections on that socket. Existing connections are not affected. Such an error can occur, for example, if the process runs out of available file descriptors. The default value is 1000 ms.

int mrpc_set_keepalive_enabled	(	struct mrpc_conn_set *	set,
		int	enabled
	)

Set whether keepalives will be enabled on new connections.

Parameters:

	set	The connection set to configure
	enabled	Nonzero to enable keepalive, zero to disable it

Returns:

A POSIX error code, or 0 on success

Configure whether keepalives will be enabled on newly-created connections. Existing connections will not be affected. The default is to enable keepalives.

int mrpc_set_keepalive_parameters	(	struct mrpc_conn_set *	set,
		unsigned	idletime,
		unsigned	count,
		unsigned	interval
	)

Set TCP keepalive parameters for new connections.

Parameters:

	set	The connection set to configure
	idletime	The number of seconds a connection can be idle before keepalive probes are sent (default: 7200)
	count	The number of keepalive probes to send before closing the connection (default: 9)
	interval	The number of seconds between keepalive probe attempts (default: 75)

Returns:

A POSIX error code, or 0 on success

Configure parameters for TCP keepalives. These settings will only be applied to new connections, and only if keepalives are enabled. These settings will be ignored for connections not using TCP.