trunk.h File Reference

#include <freeradius-devel/server/connection.h>
#include <freeradius-devel/server/request.h>
#include <freeradius-devel/server/cf_parse.h>

Include dependency graph for trunk.h:

Go to the source code of this file.

Data Structures
struct	trunk_conf_t
	Common configuration parameters for a trunk. More...
struct	trunk_connection_pub_s
	Public fields for the trunk connection. More...
struct	trunk_io_funcs_t
	I/O functions to pass to trunk_alloc. More...
struct	trunk_pub_s
	Public fields for the trunk. More...
struct	trunk_request_pub_s
	Public fields for the trunk request. More...

Macros
#define	_CONST   const
#define	TRUNK_CONN_ALL
	All connection states.
#define	TRUNK_CONN_PROCESSING
	States where the connection may be processing requests.
#define	TRUNK_CONN_SERVICEABLE
	States where the connection may potentially be used to send requests.
#define	TRUNK_CONNECTION_VERIFY(_tconn)   trunk_connection_verify(__FILE__, __LINE__, _tconn)
#define	TRUNK_NOTIFY_FUNC(_name, _type)
	Helper macro for building generic trunk notify callback.
#define	TRUNK_REQUEST_STATE_ALL
	All request states.
#define	TRUNK_REQUEST_STATE_CANCEL_ALL
	All requests in various cancellation states.
#define	TRUNK_REQUEST_VERIFY(_treq)   trunk_request_verify(__FILE__, __LINE__, _treq)
#define	TRUNK_VERIFY(_trunk)   trunk_verify(__FILE__, __LINE__, _trunk)

Typedefs
typedef connection_t *(*	trunk_connection_alloc_t) (trunk_connection_t *tconn, fr_event_list_t *el, connection_conf_t const *conf, char const *log_prefix, void *uctx)
	Allocate a new connection for the trunk.
typedef void(*	trunk_connection_notify_t) (trunk_connection_t *tconn, connection_t *conn, fr_event_list_t *el, trunk_connection_event_t notify_on, void *uctx)
	Inform the trunk API client which I/O events the trunk wants to receive.
typedef struct trunk_connection_pub_s	trunk_connection_t
typedef void(*	trunk_request_cancel_mux_t) (fr_event_list_t *el, trunk_connection_t *tconn, connection_t *conn, void *uctx)
	Inform a remote service like a datastore that a request should be cancelled.
typedef void(*	trunk_request_cancel_t) (connection_t *conn, void *preq_to_reset, trunk_cancel_reason_t reason, void *uctx)
	Remove an outstanding "sent" request from a tracking/matching structure.
typedef void(*	trunk_request_complete_t) (request_t *request, void *preq, void *rctx, void *uctx)
	Write a successful result to the rctx so that the trunk API client is aware of the result.
typedef void(*	trunk_request_conn_release_t) (connection_t *conn, void *preq_to_reset, void *uctx)
	Free connection specific resources from a treq, as the treq is being removed from a connection.
typedef void(*	trunk_request_demux_t) (fr_event_list_t *el, trunk_connection_t *tconn, connection_t *conn, void *uctx)
	Demultiplex on or more responses, reading them from a connection, decoding them, and matching them with their requests.
typedef void(*	trunk_request_fail_t) (request_t *request, void *preq, void *rctx, trunk_request_state_t state, void *uctx)
	Write a failure result to the rctx so that the trunk API client is aware that the request failed.
typedef void(*	trunk_request_free_t) (request_t *request, void *preq_to_free, void *uctx)
	Free resources associated with a trunk request.
typedef void(*	trunk_request_mux_t) (fr_event_list_t *el, trunk_connection_t *tconn, connection_t *conn, void *uctx)
	Multiplex one or more requests into a single connection.
typedef struct trunk_request_pub_s	trunk_request_t
typedef struct trunk_pub_s	trunk_t
typedef struct trunk_watch_entry_s	trunk_watch_entry_t
typedef void(*	trunk_watch_t) (trunk_t *trunk, trunk_state_t prev, trunk_state_t state, void *uctx)
	Receive a notification when a trunk enters a particular state.

Enumerations
enum	trunk_cancel_reason_t {   TRUNK_CANCEL_REASON_NONE = 0 ,   TRUNK_CANCEL_REASON_SIGNAL ,   TRUNK_CANCEL_REASON_MOVE ,   TRUNK_CANCEL_REASON_REQUEUE }
	Reasons for a request being cancelled. More...
enum	trunk_connection_event_t {   TRUNK_CONN_EVENT_NONE = 0x00 ,   TRUNK_CONN_EVENT_READ = 0x01 ,   TRUNK_CONN_EVENT_WRITE = 0x02 ,   TRUNK_CONN_EVENT_BOTH = 0x03 }
	What type of I/O events the trunk connection is currently interested in receiving. More...
enum	trunk_connection_state_t {   TRUNK_CONN_HALTED = 0x0000 ,   TRUNK_CONN_INIT = 0x0001 ,   TRUNK_CONN_CONNECTING = 0x0002 ,   TRUNK_CONN_ACTIVE = 0x0004 ,   TRUNK_CONN_CLOSED = 0x0008 ,   TRUNK_CONN_FULL = 0x0010 ,   TRUNK_CONN_INACTIVE = 0x0020 ,   TRUNK_CONN_INACTIVE_DRAINING = 0x0040 ,   TRUNK_CONN_DRAINING = 0x0080 ,   TRUNK_CONN_DRAINING_TO_FREE = 0x0100 }
	Used for sanity checks and to track which list the connection is in. More...
enum	trunk_enqueue_t {   TRUNK_ENQUEUE_IN_BACKLOG = 1 ,   TRUNK_ENQUEUE_OK = 0 ,   TRUNK_ENQUEUE_NO_CAPACITY = -1 ,   TRUNK_ENQUEUE_DST_UNAVAILABLE = -2 ,   TRUNK_ENQUEUE_FAIL = -3 }
enum	trunk_request_state_t {   TRUNK_REQUEST_STATE_INIT = 0x0000 ,   TRUNK_REQUEST_STATE_UNASSIGNED = 0x0001 ,   TRUNK_REQUEST_STATE_BACKLOG = 0x0002 ,   TRUNK_REQUEST_STATE_PENDING = 0x0004 ,   TRUNK_REQUEST_STATE_PARTIAL = 0x0008 ,   TRUNK_REQUEST_STATE_SENT = 0x0010 ,   TRUNK_REQUEST_STATE_REAPABLE = 0x0020 ,   TRUNK_REQUEST_STATE_COMPLETE = 0x0040 ,   TRUNK_REQUEST_STATE_FAILED = 0x0080 ,   TRUNK_REQUEST_STATE_CANCEL = 0x0100 ,   TRUNK_REQUEST_STATE_CANCEL_SENT = 0x0200 ,   TRUNK_REQUEST_STATE_CANCEL_PARTIAL = 0x0400 ,   TRUNK_REQUEST_STATE_CANCEL_COMPLETE = 0x0800 }
	Used for sanity checks and to simplify freeing. More...
enum	trunk_state_t {   TRUNK_STATE_IDLE = 0 ,   TRUNK_STATE_ACTIVE ,   TRUNK_STATE_PENDING ,   TRUNK_STATE_MAX }

Functions
bool	trunk_connection_search (trunk_connection_t *tconn, void *ptr)
void	trunk_connection_verify (char const *file, int line, trunk_connection_t *tconn)
bool	trunk_request_search (trunk_request_t *treq, void *ptr)
void	trunk_request_verify (char const *file, int line, trunk_request_t *treq)
bool	trunk_search (trunk_t *trunk, void *ptr)
void	trunk_verify (char const *file, int line, trunk_t *trunk)
	Verify a trunk.

Variables
conf_parser_t const	trunk_config []
	Config parser definitions to populate a trunk_conf_t.

Statistics
uint16_t	trunk_connection_count_by_state (trunk_t *trunk, int conn_state)
	Return the count number of connections in the specified states.
uint32_t	trunk_request_count_by_connection (trunk_connection_t const *tconn, int req_state)
	Return the count number of requests associated with a trunk connection.
uint64_t	trunk_request_count_by_state (trunk_t *trunk, int conn_state, int req_state)
	Return a count of requests on a connection in a specific state.

Request state signalling
void	trunk_request_signal_cancel (trunk_request_t *treq)
	Cancel a trunk request.
void	trunk_request_signal_cancel_complete (trunk_request_t *treq)
	Signal that a remote server acked our cancellation.
void	trunk_request_signal_cancel_partial (trunk_request_t *treq)
	Signal a partial cancel write.
void	trunk_request_signal_cancel_sent (trunk_request_t *treq)
	Signal that a remote server has been notified of the cancellation.
void	trunk_request_signal_complete (trunk_request_t *treq)
	Signal that a trunk request is complete.
void	trunk_request_signal_fail (trunk_request_t *treq)
	Signal that a trunk request failed.
void	trunk_request_signal_partial (trunk_request_t *treq)
	Signal a partial write.
void	trunk_request_signal_reapable (trunk_request_t *treq)
	Signal that the request was written to a connection successfully, but no response is expected.
void	trunk_request_signal_sent (trunk_request_t *treq)
	Signal that the request was written to a connection successfully.

(R)enqueue and alloc requests
uint64_t	trunk_connection_requests_requeue (trunk_connection_t *tconn, int states, uint64_t max, bool fail_bound)
	Move requests off of a connection and requeue elsewhere.
trunk_request_t *	trunk_request_alloc (trunk_t *trunk, request_t *request))
	(Pre-)Allocate a new trunk request
trunk_enqueue_t	trunk_request_enqueue (trunk_request_t **treq, trunk_t *trunk, request_t *request, void *preq, void *rctx))
	Enqueue a request that needs data written to the trunk.
trunk_enqueue_t	trunk_request_enqueue_on_conn (trunk_request_t **treq_out, trunk_connection_t *tconn, request_t *request, void *preq, void *rctx, bool ignore_limits))
	Enqueue additional requests on a specific connection.
void	trunk_request_free (trunk_request_t **treq)
	If the trunk request is freed then update the target requests.
trunk_enqueue_t	trunk_request_requeue (trunk_request_t *treq)
	Re-enqueue a request on the same connection.
void	trunk_request_state_log (fr_log_t const *log, fr_log_type_t log_type, char const *file, int line, trunk_request_t const *treq)

Dequeue protocol requests and cancellations
int	trunk_connection_pop_cancellation (trunk_request_t **treq_out, trunk_connection_t *tconn)
	Pop a cancellation request off a connection's cancellation queue.
int	trunk_connection_pop_request (trunk_request_t **treq_out, trunk_connection_t *tconn)
	Pop a request off a connection's pending queue.

Connection state signalling
The following states are signalled from I/O event handlers: writable - The connection is writable (the muxer will be called). readable - The connection is readable (the demuxer will be called). reconnect - The connection is likely bad and should be reconnected. If the code signalling has access to the conn, connection_signal_reconnect can be used instead of trunk_connection_signal_reconnect. The following states are signalled to control whether a connection may be assigned new requests: inactive - The connection cannot accept any new requests. Either due to congestion or some other administrative reason. active - The connection can, once again, accept new requests. Note: In normal operation a connection will automatically transition between the active and inactive states if conf->max_req_per_conn is specified and the number of pending requests on that connection are equal to that number. If however, the connection has previously been signalled inactive, it will not automatically be reactivated once the number of requests drops below max_req_per_conn. For other connection states the trunk API should not be signalled directly. It will be informed by "watch" callbacks inserted into the connection_t as to when the connection changes state. trunk_connection_signal_active does not need to be called in any of the connection_t state callbacks. It is only used to activate a connection which has been previously marked inactive using trunk_connection_signal_inactive. If trunk_connection_signal_inactive is being used to remove a congested connection from the active list (i.e. on receipt of an explicit protocol level congestion notification), consider calling trunk_connection_requests_requeue with the TRUNK_REQUEST_STATE_PENDING state to redistribute that connection's backlog to other connections in the trunk.
bool	trunk_connection_in_state (trunk_connection_t *tconn, int state)
	Returns true if the trunk connection is in one of the specified states.
void	trunk_connection_signal_active (trunk_connection_t *tconn)
	Signal a trunk connection is no longer full.
void	trunk_connection_signal_inactive (trunk_connection_t *tconn)
	Signal a trunk connection cannot accept more requests.
void	trunk_connection_signal_readable (trunk_connection_t *tconn)
	Signal that a trunk connection is readable.
void	trunk_connection_signal_reconnect (trunk_connection_t *tconn, connection_reason_t reason)
	Signal a trunk connection is no longer viable.
void	trunk_connection_signal_writable (trunk_connection_t *tconn)
	Signal that a trunk connection is writable.

Connection Callbacks
void	trunk_connection_callback_readable (fr_event_list_t *el, int fd, int flags, void *uctx)
void	trunk_connection_callback_writable (fr_event_list_t *el, int fd, int flags, void *uctx)

Connection management
void	trunk_reconnect (trunk_t *trunk, int state, connection_reason_t reason)
	Force the trunk to re-establish its connections.

Trunk allocation
trunk_t *	trunk_alloc (TALLOC_CTX *ctx, fr_event_list_t *el, trunk_io_funcs_t const *funcs, trunk_conf_t const *conf, char const *log_prefix, void const *uctx, bool delay_start))
	Allocate a new collection of connections.
int	trunk_connection_manage_schedule (trunk_t *trunk)
	Schedule a trunk management event for the next time the event loop is executed.
void	trunk_connection_manage_start (trunk_t *trunk)
	Allow the trunk to open and close connections in response to load.
void	trunk_connection_manage_stop (trunk_t *trunk)
	Stop the trunk from opening and closing connections in response to load.
int	trunk_start (trunk_t *trunk)
	Start the trunk running.

Watchers
trunk_watch_entry_t *	trunk_add_watch (trunk_t *trunk, trunk_state_t state, trunk_watch_t watch, bool oneshot, void const *uctx))
	Add a watch entry to the trunk state list.
int	trunk_del_watch (trunk_t *trunk, trunk_state_t state, trunk_watch_t watch)
	Remove a watch function from a trunk state list.

---

Data Structure Documentation

trunk_conf_t

struct trunk_conf_t

Common configuration parameters for a trunk.

Definition at line 224 of file trunk.h.

Collaboration diagram for trunk_conf_t:

Data Fields
bool	always_writable	Set to true if our ability to write requests to a connection handle is not dependent on the state of the underlying connection, i.e. if the library used to implement the connection can always receive and buffer new requests irrespective of the state of the underlying socket. If this is true, trunk_connection_signal_writable does not need to be called, and requests will be enqueued as soon as they're received.
bool	backlog_on_failed_conn	Assign requests to the backlog when there are no available connections and the last connection event was a failure, instead of failing them immediately.
fr_time_delta_t	close_delay	How long we must be below target utilisation to close an existing connection.
connection_conf_t const *	conn_conf	Connection configuration.
uint16_t	connecting	Maximum number of connections that can be in the connecting state. Used to throttle connection spawning.
fr_time_delta_t	idle_timeout	how long a connection can remain idle for
fr_time_delta_t	lifetime	Time between reconnects.
fr_time_delta_t	manage_interval	How often we run the management algorithm to open/close connections.
uint16_t	max	Maximum number of connections in the trunk.
uint32_t	max_backlog	Maximum number of requests that can be in the backlog.
uint32_t	max_req_per_conn	Maximum requests per connection. Used to determine if we need to create new connections and whether we can enqueue new requests.
uint64_t	max_uses	The maximum time a connection can be used.
uint16_t	min	Shouldn't let connections drop below this number.
fr_time_delta_t	open_delay	How long we must be above target utilisation to spawn a new connection.
fr_time_delta_t	req_cleanup_delay	How long must a request in the unassigned (free) list not have been used for before it's cleaned up and actually freed.
unsigned	req_pool_headers	How many chunk headers the talloc pool allocated with the treq should contain.
size_t	req_pool_size	The size of the talloc pool allocated with the treq.
uint16_t	start	How many connections to start.
uint32_t	target_req_per_conn	How many pending requests should ideally be running on each connection. Averaged across the 'active' set of connections.

trunk_connection_pub_s

struct trunk_connection_pub_s

Public fields for the trunk connection.

This saves the overhead of using accessors for commonly used fields in trunk connections.

Though these fields are public, they should NOT be modified by clients of the trunk API.

Definition at line 366 of file trunk.h.

Collaboration diagram for trunk_connection_pub_s:

Data Fields
connection_t *_CONST	conn	The underlying connection.
fr_time_t _CONST	last_read_success	Last time we read from the connection.
fr_time_t _CONST	last_write_success	Last time we wrote to the connection.
trunk_connection_state_t _CONST	state	What state the connection is in.
trunk_t *_CONST	trunk	Trunk this connection belongs to.

trunk_io_funcs_t

struct trunk_io_funcs_t

I/O functions to pass to trunk_alloc.

Definition at line 732 of file trunk.h.

Collaboration diagram for trunk_io_funcs_t:

Data Fields
trunk_connection_alloc_t	connection_alloc	Allocate a new connection_t.
trunk_connection_notify_t	connection_notify	Update the I/O event registrations for.
fr_heap_cmp_t	connection_prioritise	Ordering function for connections.
trunk_request_cancel_t	request_cancel	Request should be removed from tracking and should be reset to its initial state.
trunk_request_cancel_mux_t	request_cancel_mux	!< Read one or more requests from a connection. Inform an external resource that we no longer care about the result of any queries we issued for this request.
trunk_request_complete_t	request_complete	Request is complete, interpret the response contained in preq.
trunk_request_conn_release_t	request_conn_release	Any connection specific resources should be removed from the treq as it's about to be moved or freed.
trunk_request_demux_t	request_demux	!< Write one or more requests to a connection.
trunk_request_fail_t	request_fail	Request failed, write out a canned response.
trunk_request_free_t	request_free	Free the preq and any resources it holds and provide a chance to mark the request as runnable.
trunk_request_mux_t	request_mux
fr_heap_cmp_t	request_prioritise	Ordering function for requests. Controls where in the outbound queues they're inserted.

trunk_pub_s

struct trunk_pub_s

Public fields for the trunk.

This saves the overhead of using accessors for commonly used fields in the trunk.

Though these fields are public, they should NOT be modified by clients of the trunk API.

Definition at line 294 of file trunk.h.

Collaboration diagram for trunk_pub_s:

Data Fields
fr_time_t _CONST	last_above_target	Last time average utilisation went above the target value.
fr_time_t _CONST	last_below_target	Last time average utilisation went below the target value.
fr_time_t _CONST	last_closed	Last time the connection management function closed a connection.
fr_time_t _CONST	last_connected	Last time a connection connected.
fr_time_t _CONST	last_failed	Last time a connection failed.
fr_time_t _CONST	last_open	Last time the connection management function opened a connection.
fr_time_t _CONST	last_read_success	Last time we read a response.
fr_time_t _CONST	last_write_success	Last time we wrote to the connection.
uint64_t _CONST	req_alloc	The number of requests currently allocated that have not been freed or returned to the free list.
uint64_t _CONST	req_alloc_new	How many requests we've allocated.
uint64_t _CONST	req_alloc_reused	How many requests were reused.
trunk_state_t _CONST	state	Current state of the trunk.
bool _CONST	triggers	do we run the triggers?

trunk_request_pub_s

struct trunk_request_pub_s

Public fields for the trunk request.

This saves the overhead of using accessors for commonly used fields in trunk requests.

Though these fields are public, they should NOT be modified by clients of the trunk API.

Definition at line 344 of file trunk.h.

Collaboration diagram for trunk_request_pub_s:

Data Fields
void *_CONST	preq	Data for the muxer to write to the connection.
void *_CONST	rctx	Resume ctx of the module.
request_t *_CONST	request	The request that we're writing the data on behalf of.
trunk_request_state_t _CONST	state	Which list the request is now located in.
trunk_connection_t *_CONST	tconn	Connection this request belongs to.
trunk_t *_CONST	trunk	Trunk this request belongs to.

Macro Definition Documentation

_CONST

#define _CONST   const

Definition at line 47 of file trunk.h.

TRUNK_CONN_ALL

#define TRUNK_CONN_ALL

Value:

(\
        TRUNK_CONN_INIT | \
        TRUNK_CONN_CONNECTING | \
        TRUNK_CONN_ACTIVE | \
        TRUNK_CONN_CLOSED | \
        TRUNK_CONN_FULL | \
        TRUNK_CONN_INACTIVE | \
        TRUNK_CONN_DRAINING | \
        TRUNK_CONN_DRAINING_TO_FREE \
)

All connection states.

Definition at line 111 of file trunk.h.

TRUNK_CONN_PROCESSING

#define TRUNK_CONN_PROCESSING

Value:

(\
        TRUNK_CONN_ACTIVE | \
        TRUNK_CONN_FULL | \
        TRUNK_CONN_INACTIVE | \
        TRUNK_CONN_DRAINING | \
        TRUNK_CONN_INACTIVE_DRAINING | \
        TRUNK_CONN_DRAINING_TO_FREE \
)

States where the connection may be processing requests.

Definition at line 138 of file trunk.h.

TRUNK_CONN_SERVICEABLE

#define TRUNK_CONN_SERVICEABLE

Value:

(\
        TRUNK_CONN_ACTIVE | \
        TRUNK_CONN_INACTIVE | \
        TRUNK_CONN_DRAINING | \
        TRUNK_CONN_INACTIVE_DRAINING | \
        TRUNK_CONN_DRAINING_TO_FREE \
)

States where the connection may potentially be used to send requests.

Definition at line 126 of file trunk.h.

TRUNK_CONNECTION_VERIFY

#define TRUNK_CONNECTION_VERIFY

(

_tconn

)

trunk_connection_verify(__FILE__, __LINE__, _tconn)

Definition at line 930 of file trunk.h.

TRUNK_NOTIFY_FUNC

#define TRUNK_NOTIFY_FUNC	(		_name,
			_type
	)

Helper macro for building generic trunk notify callback.

Parameters

_name	of the callback function to build
_type	of the conn->h handle. Needs to contain an fd element.

Definition at line 953 of file trunk.h.

TRUNK_REQUEST_STATE_ALL

#define TRUNK_REQUEST_STATE_ALL

Value:

(\
        TRUNK_REQUEST_STATE_BACKLOG | \
        TRUNK_REQUEST_STATE_PENDING | \
        TRUNK_REQUEST_STATE_PARTIAL | \
        TRUNK_REQUEST_STATE_SENT | \
        TRUNK_REQUEST_STATE_REAPABLE | \
        TRUNK_REQUEST_STATE_COMPLETE | \
        TRUNK_REQUEST_STATE_FAILED | \
        TRUNK_REQUEST_STATE_CANCEL | \
        TRUNK_REQUEST_STATE_CANCEL_PARTIAL | \
        TRUNK_REQUEST_STATE_CANCEL_SENT | \
        TRUNK_REQUEST_STATE_CANCEL_COMPLETE \
)

All request states.

Definition at line 195 of file trunk.h.

TRUNK_REQUEST_STATE_CANCEL_ALL

#define TRUNK_REQUEST_STATE_CANCEL_ALL

Value:

(\
        TRUNK_REQUEST_STATE_CANCEL | \
        TRUNK_REQUEST_STATE_CANCEL_PARTIAL | \
        TRUNK_REQUEST_STATE_CANCEL_SENT | \
        TRUNK_REQUEST_STATE_CANCEL_COMPLETE \
)

All requests in various cancellation states.

Definition at line 213 of file trunk.h.

TRUNK_REQUEST_VERIFY

#define TRUNK_REQUEST_VERIFY

(

_treq

)

trunk_request_verify(__FILE__, __LINE__, _treq)

Definition at line 931 of file trunk.h.

TRUNK_VERIFY

#define TRUNK_VERIFY

(

_trunk

)

trunk_verify(__FILE__, __LINE__, _trunk)

Definition at line 929 of file trunk.h.

Typedef Documentation

trunk_connection_alloc_t

typedef connection_t *(* trunk_connection_alloc_t) (trunk_connection_t *tconn, fr_event_list_t *el, connection_conf_t const *conf, char const *log_prefix, void *uctx)

Allocate a new connection for the trunk.

The trunk code only interacts with underlying connections via the connection API. As a result the trunk API is shielded from the implementation details of opening and closing connections.

When creating new connections, this callback is used to allocate and configure a new connection_t, this connection_t and the connection API is how the trunk signals the underlying connection that it should start, reconnect, and halt (stop).

The trunk must be informed when the underlying connection is readable, and, if always_writable == false, when the connection is writable.

When the connection is readable, a read I/O handler installed by the init() callback of the connection_t must either:

• If there's no underlying I/O library, call trunk_connection_signal_readable(tconn) immediately, relying on the trunk demux callback to perform decoding and demuxing.
• If there is an underlying I/O library, feed any incoming data to that library and then call trunk_connection_signal_readable if the underlying I/O library indicates complete responses are ready for processing.

When the connection is writable a write I/O handler installed by the open() callback of the connection_t must either:

• If always_writable == true - Inform the underlying I/O library that the connection is writable. The trunk API does not need to be informed as it will immediately pass through any enqueued requests to the I/O library.
• If always_writable == false and there's an underlying I/O library, call trunk_connection_signal_writable(tconn) to allow the trunk mux callback to pass requests to the underlying I/O library and (optionally) signal the I/O library that the connection is writable.
• If always_writable == false and there's no underlying I/O library, call trunk_connection_signal_writable(tconn) to allow the trunk mux callback to encode and write requests to a socket.

Parameters

[in]	tconn	The trunk connection this connection will be bound to. Should be used as the context for any connection_t allocated.
[in]	el	The event list to use for I/O and timer events.
[in]	conf	Configuration of the connection_t.
[in]	log_prefix	What to prefix connection log messages with.
[in]	uctx	User context data passed to trunk_alloc.

Returns

• A new connection_t on success (should be in the halted state - the default).
• NULL on error.

Definition at line 432 of file trunk.h.

trunk_connection_notify_t

typedef void(* trunk_connection_notify_t) (trunk_connection_t *tconn, connection_t *conn, fr_event_list_t *el, trunk_connection_event_t notify_on, void *uctx)

Inform the trunk API client which I/O events the trunk wants to receive.

I/O handlers installed by this callback should call one or more of the following functions to signal that an I/O event has occurred:

• trunk_connection_signal_writable - Connection is now writable.
• trunk_connection_signal_readable - Connection is now readable.
• trunk_connection_signal_inactive - Connection is full or congested.
• trunk_connection_signal_active - Connection is no longer full or congested.
• trunk_connection_signal_reconnect - Connection is inviable and should be reconnected.

Parameters

[in]	tconn	That should be notified of I/O events.
[in]	conn	The connection_t bound to the tconn. Use conn->h to access the connection handle or file descriptor.
[in]	el	to insert I/O events into.
[in]	notify_on	I/O events to signal the trunk connection on.
[in]	uctx	User context data passed to trunk_alloc.

Definition at line 455 of file trunk.h.

trunk_connection_t

typedef struct trunk_connection_pub_s trunk_connection_t

Definition at line 45 of file trunk.h.

trunk_request_cancel_mux_t

typedef void(* trunk_request_cancel_mux_t) (fr_event_list_t *el, trunk_connection_t *tconn, connection_t *conn, void *uctx)

Inform a remote service like a datastore that a request should be cancelled.

This callback will be called any time there are one or more requests to be cancelled and a connection_t is writable, or as soon as a request is cancelled if always_writable == true.

For efficiency, this callback should call trunk_connection_pop_cancellation multiple times, and process all outstanding cancellation requests.

If the response (cancel ACK) from the remote service needs to be tracked, then the treq should be inserted into a tracking tree shared with the demuxer, and trunk_request_signal_cancel_sent should be called to move the treq into the cancel_sent state.

As with the main mux callback, if a cancellation request is partially written trunk_request_signal_cancel_partial should be called, and the amount of data written should be tracked in the preq (protocol request).

When the demuxer finds a matching (cancel ACK) response, the demuxer should remove the entry from the tracking tree and call trunk_request_signal_cancel_complete.

Parameters

[in]	el	To insert any timers into.
[in]	tconn	The trunk connection used to dequeue cancellation requests.
[in]	conn	Connection to write the request to. Use conn->h to access the connection handle or file descriptor.
[in]	uctx	User context data passed to trunk_alloc.

Definition at line 575 of file trunk.h.

trunk_request_cancel_t

typedef void(* trunk_request_cancel_t) (connection_t *conn, void *preq_to_reset, trunk_cancel_reason_t reason, void *uctx)

Remove an outstanding "sent" request from a tracking/matching structure.

If the treq (trunk request) is in the TRUNK_REQUEST_STATE_PARTIAL or TRUNK_REQUEST_STATE_SENT states, this callback will be called prior to moving the treq to a new connection, requeueing the treq or freeing the treq.

The treq, and any associated resources, should be removed from the the matching structure associated with the connection_t or uctx.

Which resources should be freed depends on the cancellation reason:

• TRUNK_CANCEL_REASON_REQUEUE - If an encoded request can be reused, then it should be kept, otherwise it should be freed. Any resources like ID allocations bound to that request should also be freed. trunk_request_conn_release_t callback will not be called in this instance and cannot be used as an alternative.
• TRUNK_CANCEL_REASON_MOVE - If an encoded request can be reused it should be kept. The trunk mux callback should be aware that an encoded request may already be associated with a preq and use that instead of re-encoding the preq. If the encoded request cannot be reused it should be freed, and any fields in the preq that were modified during the last mux call (other than perhaps counters) should be reset to their initial values. Alternatively the trunk_request_conn_release_t callback can be used for the same purpose, as that will be called before the request is moved.
• TRUNK_CANCEL_REASON_SIGNAL - The encoded request and any I/O library request handled may be freed though that may (optionally) be left to another callback like trunk_request_conn_release_t, as that will be called as the treq is removed from the conn. Note that the trunk_request_complete_t and trunk_request_fail_t callbacks will not be called in this instance.

After this callback is complete one of several actions will be taken:

• If the cancellation reason was TRUNK_CANCEL_REASON_REQUEUE the treq will be placed back into the pending list of the connection it was previously associated with.
• If the cancellation reason was TRUNK_CANCEL_REASON_MOVE, the treq will move to the unassigned state, and then either be placed in the trunk backlog, or immediately enqueued on another trunk connection.
• If the reason was TRUNK_CANCEL_SIGNAL
  • ...and a request_cancel_mux callback was provided, the the request_cancel_mux callback will be called when the connection is next writable (or immediately if always_writable == true) and the request_cancel_mux callback will send an explicit cancellation request to terminate any outstanding queries on remote datastores.
  • ...and no request_cancel_mux callback was provided, the treq will enter the unassigned state and then be freed.

Note

TRUNK_CANCEL_REASON_MOVE will only be set if the underlying connection is bad. A 'sent' treq will never be moved due to load balancing.

There is no need to signal request state changes in the cancellation function. The trunk will move the request into the correct state. This callback is only to allow the API client to cleanup the preq in preparation for the cancellation event.

Cancellation requests to a remote datastore should not be made here. If that is required, a cancel_mux function should be provided.

Parameters

[in]	conn	to remove request from.
[in]	preq_to_reset	Preq to reset.
[in]	reason	Why the request was cancelled.
[in]	uctx	User context data passed to trunk_alloc.

Definition at line 648 of file trunk.h.

trunk_request_complete_t

typedef void(* trunk_request_complete_t) (request_t *request, void *preq, void *rctx, void *uctx)

Write a successful result to the rctx so that the trunk API client is aware of the result.

The rctx should be modified in such a way that indicates to the trunk API client that the request was sent using the trunk and a response was received.

This function should not free any resources associated with the preq. That should be done in the request_free callback. This function should only be used to translate the contents of the preq into a result, and write it to the rctx.

After this callback is complete, the request_free callback will be called if provided.

Definition at line 678 of file trunk.h.

trunk_request_conn_release_t

typedef void(* trunk_request_conn_release_t) (connection_t *conn, void *preq_to_reset, void *uctx)

Free connection specific resources from a treq, as the treq is being removed from a connection.

Any connection specific resources that the treq currently holds must be released. Examples are connection-specific handles, ID allocations, and connection specific packets.

The treq may be about to be freed or it may be being re-assigned to a new connection.

Parameters

[in]	conn	request will be removed from.
[in]	preq_to_reset	Preq to remove connection specified resources from.
[in]	uctx	User context data passed to trunk_alloc.

Definition at line 664 of file trunk.h.

trunk_request_demux_t

typedef void(* trunk_request_demux_t) (fr_event_list_t *el, trunk_connection_t *tconn, connection_t *conn, void *uctx)

Demultiplex on or more responses, reading them from a connection, decoding them, and matching them with their requests.

This callback should either:

• If an underlying I/O library is used, request complete responses from the I/O library, and match the responses with a treq (trunk request) using a tracking structure associated with the connection_t or uctx.
• If no underlying I/O library is used, read responses from the connection_t, decode those responses, and match those responses with a treq using a tracking structure associated with the connection_t or uctx.

The result (positive or negative), should be written to the rctx structure.

trunk_request_signal_complete should be used to inform the trunk that the request is now complete.

If a connection appears to have become unusable, this callback should call connection_signal_reconnect and immediately return. The current treq will either fail, or be re-enqueued depending on the trunk configuration.

trunk_request_signal_fail should NOT be called as this function is only used for reporting failures at an I/O layer level not failures of queries or external services.

Parameters

[in]	el	For timer management.
[in]	tconn	The trunk connection.
[in]	conn	Connection to read the request from. Use conn->h to access the connection handle or file descriptor.
[in]	uctx	User context data passed to trunk_alloc.

Definition at line 541 of file trunk.h.

trunk_request_fail_t

typedef void(* trunk_request_fail_t) (request_t *request, void *preq, void *rctx, trunk_request_state_t state, void *uctx)

Write a failure result to the rctx so that the trunk API client is aware that the request failed.

The rctx should be modified in such a way that indicates to the trunk API client that the request could not be sent using the trunk.

This function should not free any resources associated with the preq. That should be done in the request_free callback. This function should only be used to write a "canned" failure to the rctx.

Note

If a cancel function is provided, the cancel function should be used to remove active requests from any request/response matching, not the fail function. Both the cancel and fail functions will be called for a request that has been sent or partially sent.

After this callback is complete, the request_free callback will be called if provided.

Definition at line 696 of file trunk.h.

trunk_request_free_t

typedef void(* trunk_request_free_t) (request_t *request, void *preq_to_free, void *uctx)

Free resources associated with a trunk request.

The trunk request is complete. If there's a request still associated with the trunk request, that will be provided so that it can be marked runnable, but be aware that the request_t * value will be NULL if the request was cancelled due to a signal.

The preq and any associated data such as encoded packets or I/O library request handled SHOULD be explicitly freed by this function. The exception to this is if the preq is parented by the treq, in which case the preq will be explicitly freed when the treq is returned to the free list.

Parameters

[in]	request	to mark as runnable if no further processing is required.
[in]	preq_to_free	As per the name.
[in]	uctx	User context data passed to trunk_alloc.

Definition at line 715 of file trunk.h.

trunk_request_mux_t

typedef void(* trunk_request_mux_t) (fr_event_list_t *el, trunk_connection_t *tconn, connection_t *conn, void *uctx)

Multiplex one or more requests into a single connection.

This callback should:

• Pop one or more requests from the trunk connection's pending queue using trunk_connection_pop_request.
• Serialize the protocol request data contained within the trunk request's (treq's) pctx, writing it to the provided connection_t (or underlying connection handle).
• Insert the provided treq into a tracking structure associated with the connection_t or uctx. This tracking structure will be used later in the trunk demux callback to match protocol requests with protocol responses.

If working at the socket level and a write on a file descriptor indicates less data was written than was needed, the trunk API client should track the amount of data written in the protocol request (preq), and should call trunk_request_signal_partial(treq). trunk_request_signal_partial will move the request out of the pending queue, and store it in the partial slot of the trunk connection. The next time trunk_connection_pop_request is called, the partially written treq will be returned first. The API client should continue writing the partially written request to the socket.

After calling trunk_request_signal_partial this callback MUST NOT call trunk_connection_pop_request again, and should immediately return.

If the request can't be written to the connection because it the connection has become unusable, this callback should call connection_signal_reconnect(conn) to notify the connection API that the connection is unusable. The current request will either fail, or be re-enqueued depending on the trunk configuration.

After calling connection_signal_reconnect this callback MUST NOT call trunk_connection_pop_request again, and should immediately return.

If the protocol request data can't be written to the connection because the data is invalid or because some other error occurred, this callback should call trunk_request_signal_fail(treq), this callback may then continue popping/processing other requests.

Parameters

[in]	el	For timer management.
[in]	tconn	The trunk connection to dequeue trunk requests from.
[in]	conn	Connection to write the request to. Use conn->h to access the connection handle or file descriptor.
[in]	uctx	User context data passed to trunk_alloc.

Definition at line 507 of file trunk.h.

trunk_request_t

typedef struct trunk_request_pub_s trunk_request_t

Definition at line 44 of file trunk.h.

trunk_t

typedef struct trunk_pub_s trunk_t

Definition at line 46 of file trunk.h.

trunk_watch_entry_t

typedef struct trunk_watch_entry_s trunk_watch_entry_t

Definition at line 727 of file trunk.h.

trunk_watch_t

typedef void(* trunk_watch_t) (trunk_t *trunk, trunk_state_t prev, trunk_state_t state, void *uctx)

Receive a notification when a trunk enters a particular state.

Parameters

[in]	trunk	Being watched.
[in]	prev	State we came from.
[in]	state	State that was entered (the current state)
[in]	uctx	that was passed to trunk_add_watch_*.

Definition at line 724 of file trunk.h.

Enumeration Type Documentation

trunk_cancel_reason_t

enum trunk_cancel_reason_t

Reasons for a request being cancelled.

Enumerator
TRUNK_CANCEL_REASON_NONE	Request has not been cancelled.
TRUNK_CANCEL_REASON_SIGNAL	Request cancelled due to a signal.
TRUNK_CANCEL_REASON_MOVE	Request cancelled because it's being moved.
TRUNK_CANCEL_REASON_REQUEUE	A previously sent request is being requeued.

Definition at line 55 of file trunk.h.

trunk_connection_event_t

enum trunk_connection_event_t

What type of I/O events the trunk connection is currently interested in receiving.

Enumerator
TRUNK_CONN_EVENT_NONE	Don't notify the trunk on connection state changes.
TRUNK_CONN_EVENT_READ	Trunk should be notified if a connection is readable.
TRUNK_CONN_EVENT_WRITE	Trunk should be notified if a connection is writable.
TRUNK_CONN_EVENT_BOTH	Trunk should be notified if a connection is readable or writable.

Definition at line 72 of file trunk.h.

trunk_connection_state_t

enum trunk_connection_state_t

Used for sanity checks and to track which list the connection is in.

Enumerator
TRUNK_CONN_HALTED	Halted, ready to be freed.
TRUNK_CONN_INIT	In the initial state.
TRUNK_CONN_CONNECTING	Connection is connecting.
TRUNK_CONN_ACTIVE	Connection is connected and ready to service requests. This is active and not 'connected', because a connection can be 'connected' and 'full' or 'connected' and 'active'.
TRUNK_CONN_CLOSED	Connection was closed, either explicitly or due to failure.
TRUNK_CONN_FULL	Connection is full and can't accept any more requests.
TRUNK_CONN_INACTIVE	Connection is inactive and can't accept any more requests.
TRUNK_CONN_INACTIVE_DRAINING	Connection is inactive, can't accept any more requests, and will be closed once it has no more outstanding requests. Connections in this state can transition to TRUNK_CONN_DRAINING.
TRUNK_CONN_DRAINING	Connection will be closed once it has no more outstanding requests, if it's not reactivated.
TRUNK_CONN_DRAINING_TO_FREE	Connection will be closed once it has no more outstanding requests.

Definition at line 87 of file trunk.h.

trunk_enqueue_t

enum trunk_enqueue_t

Enumerator
TRUNK_ENQUEUE_IN_BACKLOG	Request should be enqueued in backlog.
TRUNK_ENQUEUE_OK	Operation was successful.
TRUNK_ENQUEUE_NO_CAPACITY	At maximum number of connections, and no connection has capacity.
TRUNK_ENQUEUE_DST_UNAVAILABLE	Destination is down.
TRUNK_ENQUEUE_FAIL	General failure.

Definition at line 148 of file trunk.h.

trunk_request_state_t

enum trunk_request_state_t

Used for sanity checks and to simplify freeing.

Allows us to track which

Enumerator
TRUNK_REQUEST_STATE_INIT	Initial state. Requests in this state were never assigned, and the request_t should not have been yielded.
TRUNK_REQUEST_STATE_UNASSIGNED	Transition state - Request currently not assigned to any connection.
TRUNK_REQUEST_STATE_BACKLOG	In the backlog.
TRUNK_REQUEST_STATE_PENDING	In the queue of a connection and is pending writing.
TRUNK_REQUEST_STATE_PARTIAL	Some of the request was written to the socket, more of it should be written later.
TRUNK_REQUEST_STATE_SENT	Was written to a socket. Waiting for a response.
TRUNK_REQUEST_STATE_REAPABLE	Request has been written, needs to persist, but we are not currently waiting for any response. This is primarily useful where the connection only allows a single outstanding request, and writing additional requests would cause the previous result to be lost. Requests in this state count towards the outstanding number of requests on a connection, and prevent new requests from being enqueued until they complete.
TRUNK_REQUEST_STATE_COMPLETE	The request is complete.
TRUNK_REQUEST_STATE_FAILED	The request failed.
TRUNK_REQUEST_STATE_CANCEL	A request on a particular socket was cancel.
TRUNK_REQUEST_STATE_CANCEL_SENT	We've informed the remote server that the request has been cancelled.
TRUNK_REQUEST_STATE_CANCEL_PARTIAL	We partially wrote a cancellation request.
TRUNK_REQUEST_STATE_CANCEL_COMPLETE	Remote server has acknowledged our cancellation.

Definition at line 161 of file trunk.h.

trunk_state_t

enum trunk_state_t

Enumerator
TRUNK_STATE_IDLE	Trunk has no connections.
TRUNK_STATE_ACTIVE	Trunk has active connections.
TRUNK_STATE_PENDING	Trunk has connections, but none are active.
TRUNK_STATE_MAX

Definition at line 62 of file trunk.h.

Function Documentation

trunk_add_watch()

trunk_watch_entry_t * trunk_add_watch	(	trunk_t *	trunk,
		trunk_state_t	state,
		trunk_watch_t	watch,
		bool	oneshot,
		void const *	uctx
	)

Add a watch entry to the trunk state list.

Parameters

[in]	trunk	The trunk to add the watcher to.
[in]	state	to watch for.
[in]	watch	Function to add.
[in]	oneshot	Should this watcher only be run once.
[in]	uctx	Context to pass to function.

Returns

• NULL if an invalid state is passed.
• A new watch entry handle on success.

Definition at line 865 of file trunk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

trunk_alloc()

trunk_t * trunk_alloc	(	TALLOC_CTX *	ctx,
		fr_event_list_t *	el,
		trunk_io_funcs_t const *	funcs,
		trunk_conf_t const *	conf,
		char const *	log_prefix,
		void const *	uctx,
		bool	delay_start
	)

Allocate a new collection of connections.

This function should be called first to allocate a new trunk connection.

After the trunk has been allocated, trunk_request_alloc and trunk_request_enqueue should be used to allocate memory for trunk requests, and pass a preq (protocol request) to the trunk for processing.

The trunk will then asynchronously process the request, writing the result to a specified rctx. See trunk_request_enqueue for more details.

Note

Trunks may not be shared between multiple threads under any circumstances.

Parameters

[in]	ctx	To use for any memory allocations. Must be thread local.
[in]	el	to use for I/O and timer events.
[in]	funcs	Callback functions.
[in]	conf	Common user configurable parameters.
[in]	log_prefix	To prepend to global messages.
[in]	uctx	User data to pass to the alloc function.
[in]	delay_start	If true, then we will not spawn any connections until the first request is enqueued.

Returns

• New trunk handle on success.
• NULL on error.

Definition at line 4945 of file trunk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

trunk_connection_callback_readable()

void trunk_connection_callback_readable	(	fr_event_list_t *	el,
		int	fd,
		int	flags,
		void *	uctx
	)

trunk_connection_callback_writable()

void trunk_connection_callback_writable	(	fr_event_list_t *	el,
		int	fd,
		int	flags,
		void *	uctx
	)

trunk_connection_count_by_state()

uint16_t trunk_connection_count_by_state	(	trunk_t *	trunk,
		int	conn_state
	)

Return the count number of connections in the specified states.

Parameters

[in]	trunk	to retrieve counts for.
[in]	conn_state	One or more trunk_connection_state_t states or'd together.

Returns

The number of connections in the specified states.

Definition at line 2855 of file trunk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

trunk_connection_in_state()

bool trunk_connection_in_state	(	trunk_connection_t *	tconn,
		int	state
	)

Returns true if the trunk connection is in one of the specified states.

Parameters

[in]	tconn	To check state for.
[in]	state	to check

Returns

• True if trunk connection is in a particular state.
• False if trunk connection is not in a particular state.

Definition at line 4047 of file trunk.c.

trunk_connection_manage_schedule()

int trunk_connection_manage_schedule

(

trunk_t *

trunk

)

Schedule a trunk management event for the next time the event loop is executed.

Definition at line 4829 of file trunk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

trunk_connection_manage_start()

void trunk_connection_manage_start

(

trunk_t *

trunk

)

Allow the trunk to open and close connections in response to load.

Definition at line 4808 of file trunk.c.

trunk_connection_manage_stop()

void trunk_connection_manage_stop

(

trunk_t *

trunk

)

Stop the trunk from opening and closing connections in response to load.

Definition at line 4819 of file trunk.c.

trunk_connection_pop_cancellation()

int trunk_connection_pop_cancellation	(	trunk_request_t **	treq_out,
		trunk_connection_t *	tconn
	)

Pop a cancellation request off a connection's cancellation queue.

The request we return is advanced by the request moving out of the cancel state and into the cancel_sent or cancel_complete state.

One of these signalling functions must be called after the request has been popped:

• trunk_request_signal_cancel_sent The remote datastore has been informed, but we need to wait for acknowledgement. The trunk_request_demux_t callback must handle the acks calling trunk_request_signal_cancel_complete when an ack is received.
• trunk_request_signal_cancel_complete The request was cancelled and we don't need to wait, clean it up immediately.

Parameters

[out]	treq_out	to process
[in]	tconn	Connection to drain cancellation request from.

Returns

• 1 if no more requests.
• 0 if a new request was written to treq_out.
• -1 if the connection was previously freed. Caller MUST NOT touch any memory or requests associated with the connection.
• -2 if called outside of the cancel muxer.

Definition at line 3835 of file trunk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

trunk_connection_pop_request()

int trunk_connection_pop_request	(	trunk_request_t **	treq_out,
		trunk_connection_t *	tconn
	)

Pop a request off a connection's pending queue.

The request we return is advanced by the request moving out of the partial or pending states, when the mux function signals us.

If the same request is returned again and again, it means the muxer isn't actually doing anything with the request we returned, and it's and error in the muxer code.

One of these signalling functions must be used after the request has been popped:

• trunk_request_signal_complete The request was completed. Either we got a synchronous response, or we knew the response without contacting an external server (cache).
• trunk_request_signal_fail Failed muxing the request due to a permanent issue, i.e. an invalid request.
• trunk_request_signal_partial Wrote part of a request. This request will be returned on the next call to this function so that the request_mux function can finish writing it. Only useful for stream type connections. Datagram type connections cannot have partial writes.
• trunk_request_signal_sent Successfully sent a request.

Parameters

[out]	treq_out	to process
[in]	tconn	to pop a request from.

Returns

• 1 if no more requests.
• 0 if a new request was written to treq_out.
• -1 if the connection was previously freed. Caller MUST NOT touch any memory or requests associated with the connection.
• -2 if called outside of the muxer.

Definition at line 3883 of file trunk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

trunk_connection_requests_requeue()

uint64_t trunk_connection_requests_requeue	(	trunk_connection_t *	tconn,
		int	states,
		uint64_t	max,
		bool	fail_bound
	)

Move requests off of a connection and requeue elsewhere.

Note

We don't re-queue on draining or draining to free, as requests should have already been moved off of the connection. It's also dangerous as the trunk management code main clean up a connection in this state when it's run on re-queue, and then the caller may try and access a now freed connection.

Parameters

[in]	tconn	to move requests off of.
[in]	states	Only move requests in this state.
[in]	max	The maximum number of requests to dequeue. 0 for unlimited.
[in]	fail_bound	If true causes any requests bound to the connection to fail. If false bound requests will not be moved.

Returns

The number of requests requeued.

Definition at line 2010 of file trunk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

trunk_connection_search()

bool trunk_connection_search	(	trunk_connection_t *	tconn,
		void *	ptr
	)

Definition at line 5203 of file trunk.c.

trunk_connection_signal_active()

void trunk_connection_signal_active

(

trunk_connection_t *

tconn

)

Signal a trunk connection is no longer full.

Parameters

[in]

tconn

to signal.

Definition at line 3960 of file trunk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

trunk_connection_signal_inactive()

void trunk_connection_signal_inactive

(

trunk_connection_t *

tconn

)

Signal a trunk connection cannot accept more requests.

Parameters

[in]

tconn

to signal.

Definition at line 3937 of file trunk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

trunk_connection_signal_readable()

void trunk_connection_signal_readable

(

trunk_connection_t *

tconn

)

Signal that a trunk connection is readable.

Should be called from the 'read' I/O handler to signal that requests should be dequeued.

Parameters

[in]

tconn

to signal.

Definition at line 3921 of file trunk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

trunk_connection_signal_reconnect()

void trunk_connection_signal_reconnect	(	trunk_connection_t *	tconn,
		connection_reason_t	reason
	)

Signal a trunk connection is no longer viable.

Parameters

[in]	tconn	to signal.
[in]	reason	the connection is being reconnected.

Definition at line 3999 of file trunk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

trunk_connection_signal_writable()

void trunk_connection_signal_writable

(

trunk_connection_t *

tconn

)

Signal that a trunk connection is writable.

Should be called from the 'write' I/O handler to signal that requests can be enqueued.

Parameters

[in]

tconn

to signal.

Definition at line 3903 of file trunk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

trunk_connection_verify()

void trunk_connection_verify	(	char const *	file,
		int	line,
		trunk_connection_t *	tconn
	)

Definition at line 5087 of file trunk.c.

trunk_del_watch()

int trunk_del_watch	(	trunk_t *	trunk,
		trunk_state_t	state,
		trunk_watch_t	watch
	)

Remove a watch function from a trunk state list.

Parameters

[in]	trunk	The trunk to remove the watcher from.
[in]	state	to remove the watch from.
[in]	watch	Function to remove.

Returns

• 0 if the function was removed successfully.
• -1 if the function wasn't present in the watch list.
• -2 if an invalid state was passed.

Definition at line 831 of file trunk.c.

Here is the call graph for this function:

trunk_reconnect()

void trunk_reconnect	(	trunk_t *	trunk,
		int	states,
		connection_reason_t	reason
	)

Force the trunk to re-establish its connections.

Parameters

[in]	trunk	to signal.
[in]	states	One or more states or'd together.
[in]	reason	Why the connections are being signalled to reconnect.

Definition at line 4725 of file trunk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

trunk_request_alloc()

trunk_request_t * trunk_request_alloc	(	trunk_t *	trunk,
		request_t *	request
	)

(Pre-)Allocate a new trunk request

If trunk->conf.req_pool_headers or trunk->conf.req_pool_size are not zero then the request will be a talloc pool, which can be used to hold the preq.

Note

Do not use MEM to check the result of this allocated as it may fail for non-fatal reasons.

Parameters

[in]	trunk	to add request to.
[in]	request	to wrap in a trunk request (treq).

Returns

• A newly allocated request.
• NULL if too many requests are allocated.

Definition at line 2474 of file trunk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

trunk_request_count_by_connection()

uint32_t trunk_request_count_by_connection	(	trunk_connection_t const *	tconn,
		int	req_state
	)

Return the count number of requests associated with a trunk connection.

Parameters

[in]	tconn	to return request count for.
[in]	req_state	One or more request states or'd together.

Returns

The number of requests in the specified states, associated with a tconn.

Definition at line 2879 of file trunk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

trunk_request_count_by_state()

uint64_t trunk_request_count_by_state	(	trunk_t *	trunk,
		int	conn_state,
		int	req_state
	)

Return a count of requests on a connection in a specific state.

Parameters

[in]	trunk	to retrieve counts for.
[in]	conn_state	One or more connection states or'd together.
[in]	req_state	One or more request states or'd together.

Returns

The number of requests in a particular state, on connection in a particular state.

Definition at line 4522 of file trunk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

trunk_request_enqueue()

trunk_enqueue_t trunk_request_enqueue	(	trunk_request_t **	treq_out,
		trunk_t *	trunk,
		request_t *	request,
		void *	preq,
		void *	rctx
	)

Enqueue a request that needs data written to the trunk.

When a request_t * needs to make an asynchronous request to an external datastore it should call this function, specifying a preq (protocol request) containing the data necessary to request information from the external datastore, and an rctx (resume ctx) used to hold the decoded response and/or any error codes.

After a treq is successfully enqueued it will either be assigned immediately to the pending queue of a connection, or if no connections are available, (depending on the trunk configuration) the treq will be placed in the trunk's global backlog.

After receiving a positive return code from this function the caller should immediately yield, to allow the various timers and I/O handlers that drive tconn (trunk connection) and treq state changes to be called.

When a tconn becomes writable (or the trunk is configured to be always writable) the trunk_request_mux_t callback will be called to dequeue, encode and send any pending requests for that tconn. The trunk_request_mux_t callback is also responsible for tracking the outbound requests to allow the trunk_request_demux_t callback to match inbound responses with the original treq. Once the trunk_request_mux_t callback is done processing the treq it signals what state the treq should enter next using one of the trunk_request_signal_* functions.

When a tconn becomes readable the user specified trunk_request_demux_t callback is called to process any responses, match them with the original treq. and signal what state they should enter next using one of the trunk_request_signal_* functions.

Parameters

[in,out]	treq_out	A trunk request handle. If the memory pointed to is NULL, a new treq will be allocated. Otherwise treq should point to memory allocated with trunk_request_alloc.
[in]	trunk	to enqueue request on.
[in]	request	to enqueue.
[in]	preq	Protocol request to write out. Will be freed when treq is freed. Should ideally be parented by the treq if possible. Use trunk_request_alloc for pre-allocation of the treq.
[in]	rctx	The resume context to write any result to.

Returns

• TRUNK_ENQUEUE_OK.
• TRUNK_ENQUEUE_IN_BACKLOG.
• TRUNK_ENQUEUE_NO_CAPACITY.
• TRUNK_ENQUEUE_DST_UNAVAILABLE
• TRUNK_ENQUEUE_FAIL

Definition at line 2587 of file trunk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

trunk_request_enqueue_on_conn()

trunk_enqueue_t trunk_request_enqueue_on_conn	(	trunk_request_t **	treq_out,
		trunk_connection_t *	tconn,
		request_t *	request,
		void *	preq,
		void *	rctx,
		bool	ignore_limits
	)

Enqueue additional requests on a specific connection.

This may be used to create a series of requests on a single connection, or to generate in-band status checks.

Note

If conf->always_writable, then the muxer will be called immediately. The caller must be able to handle multiple calls to its muxer gracefully.

Parameters

[in,out]	treq_out	A trunk request handle. If the memory pointed to is NULL, a new treq will be allocated. Otherwise treq should point to memory allocated with trunk_request_alloc.
[in]	tconn	to enqueue request on.
[in]	request	to enqueue.
[in]	preq	Protocol request to write out. Will be freed when treq is freed. Should ideally be parented by the treq if possible. Use trunk_request_alloc for pre-allocation of the treq.
[in]	rctx	The resume context to write any result to.
[in]	ignore_limits	Ignore max_req_per_conn. Useful to force status checks through even if the connection is at capacity. Will also allow enqueuing on "inactive", "draining", "draining-to-free" connections.

Returns

• TRUNK_ENQUEUE_OK.
• TRUNK_ENQUEUE_NO_CAPACITY - At max_req_per_conn_limit
• TRUNK_ENQUEUE_DST_UNAVAILABLE - Connection cannot service requests.

Definition at line 2741 of file trunk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

trunk_request_free()

void trunk_request_free

(

trunk_request_t **

treq_to_free

)

If the trunk request is freed then update the target requests.

gperftools showed calling the request free function directly was slightly faster than using talloc_free.

Parameters

[in]

treq_to_free

request.

Definition at line 2322 of file trunk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

trunk_request_requeue()

trunk_enqueue_t trunk_request_requeue

(

trunk_request_t *

treq

)

Re-enqueue a request on the same connection.

If the treq has been sent, we assume that we're being signalled to requeue because something outside of the trunk API has determined that a retransmission is required. The easiest way to perform that retransmission is to clean up any tracking information for the request, and the requeue it for transmission.

IF re-queueing fails, the request will enter the fail state. It should not be accessed if this occurs.

Parameters

[in]

treq

to requeue (retransmit).

Returns

• TRUNK_ENQUEUE_OK.
• TRUNK_ENQUEUE_DST_UNAVAILABLE - Connection cannot service requests.
• TRUNK_ENQUEUE_FAIL - Request isn't in a valid state to be reassigned.

Definition at line 2676 of file trunk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

trunk_request_search()

bool trunk_request_search	(	trunk_request_t *	treq,
		void *	ptr
	)

Definition at line 5261 of file trunk.c.

trunk_request_signal_cancel()

void trunk_request_signal_cancel

(

trunk_request_t *

treq

)

Cancel a trunk request.

treq can be in any state, but requests to cancel if the treq is not in the TRUNK_REQUEST_STATE_PARTIAL or TRUNK_REQUEST_STATE_SENT state will be ignored.

The complete or failed callbacks will not be called here, as it's assumed the request_t * is now inviable as it's being cancelled.

The free function however, is called, and that should be used to perform necessary cleanup.

Parameters

[in]

treq

to signal state change for.

Definition at line 2152 of file trunk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

trunk_request_signal_cancel_complete()

void trunk_request_signal_cancel_complete

(

trunk_request_t *

treq

)

Signal that a remote server acked our cancellation.

Called from request_demux to indicate that it got an ack for the cancellation.

Parameters

[in]

treq

to signal state change for.

Definition at line 2284 of file trunk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

trunk_request_signal_cancel_partial()

void trunk_request_signal_cancel_partial

(

trunk_request_t *

treq

)

Signal a partial cancel write.

Where there's high load, and the outbound write buffer is full

Parameters

[in]

treq

to signal state change for.

Definition at line 2236 of file trunk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

trunk_request_signal_cancel_sent()

void trunk_request_signal_cancel_sent

(

trunk_request_t *

treq

)

Signal that a remote server has been notified of the cancellation.

Called from request_cancel_mux to indicate that the datastore has been informed that the response is no longer needed.

Parameters

[in]

treq

to signal state change for.

Definition at line 2260 of file trunk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

trunk_request_signal_complete()

void trunk_request_signal_complete

(

trunk_request_t *

treq

)

Signal that a trunk request is complete.

The API client will be informed that the request is now complete.

Definition at line 2094 of file trunk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

trunk_request_signal_fail()

void trunk_request_signal_fail

(

trunk_request_t *

treq

)

Signal that a trunk request failed.

The API client will be informed that the request has failed.

Definition at line 2132 of file trunk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

trunk_request_signal_partial()

void trunk_request_signal_partial

(

trunk_request_t *

treq

)

Signal a partial write.

Where there's high load, and the outbound write buffer is full

Parameters

[in]

treq

to signal state change for.

Definition at line 2029 of file trunk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

trunk_request_signal_reapable()

void trunk_request_signal_reapable

(

trunk_request_t *

treq

)

Signal that the request was written to a connection successfully, but no response is expected.

Parameters

[in]

treq

to signal state change for.

Definition at line 2072 of file trunk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

trunk_request_signal_sent()

void trunk_request_signal_sent

(

trunk_request_t *

treq

)

Signal that the request was written to a connection successfully.

Parameters

[in]

treq

to signal state change for.

Definition at line 2050 of file trunk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

trunk_request_state_log()

void trunk_request_state_log	(	fr_log_t const *	log,
		fr_log_type_t	log_type,
		char const *	file,
		int	line,
		trunk_request_t const *	treq
	)

Definition at line 2828 of file trunk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

trunk_request_verify()

void trunk_request_verify	(	char const *	file,
		int	line,
		trunk_request_t *	treq
	)

Definition at line 5147 of file trunk.c.

Here is the call graph for this function:

trunk_search()

bool trunk_search	(	trunk_t *	trunk,
		void *	ptr
	)

Definition at line 5158 of file trunk.c.

trunk_start()

int trunk_start

(

trunk_t *

trunk

)

Start the trunk running.

Definition at line 4764 of file trunk.c.

Here is the call graph for this function:

Here is the caller graph for this function:

trunk_verify()

void trunk_verify	(	char const *	file,
		int	line,
		trunk_t *	trunk
	)

Verify a trunk.

A trunk has some number of connections, which each have some number of requests. The connections and requests are in differing kinds of containers depending on their state and how they are used, and may have fields that can only be validated by comparison with a parent. We had planned on passing a "context" down with the ancestral values, but that breaks the foo_verify() API. Each foo_verify() will only verify the foo's children.

Definition at line 5026 of file trunk.c.

Here is the call graph for this function:

Variable Documentation

trunk_config

conf_parser_t const trunk_config[]

extern

Config parser definitions to populate a trunk_conf_t.

Definition at line 315 of file trunk.c.