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. |
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:
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.
#define MRPC_VERSION_CODE | ( | ) |
Get the version code for the miniRPC headers the application was compiled against.
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.
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.
code | The version code |
#define MRPC_VERSION_MINOR | ( | code | ) |
Extract a minor version number from a version code.
code | The version code |
#define MRPC_VERSION_REVISION | ( | code | ) |
Extract a revision number from a version code.
code | The version code |
int mrpc_version_code | ( | void | ) |
Get the version code for the miniRPC library the application is running against.
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.
[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 |
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.
set | The connection set |
Get an additional reference to the specified connection set.
void mrpc_conn_set_unref | ( | struct mrpc_conn_set * | set | ) |
Decrement the refcount of a connection set.
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:
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.
set | The connection set to configure | |
func | The accept function |
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.
set | The connection set to configure | |
func | The disconnect function, or NULL for none |
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.
set | The connection set to configure | |
func | The ioerr function, or NULL for none |
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.
set | The connection set to configure | |
len | The maximum payload length in bytes. Must be greater than zero. |
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.
set | The connection set to configure | |
backlog | The length of the backlog queue. Must be greater than zero. |
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.
set | The connection set to configure | |
ms | The number of milliseconds to wait. Must be greater than zero. |
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.
set | The connection set to configure | |
enabled | Nonzero to enable keepalive, zero to disable it |
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.
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) |
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.