control-plane signaling More...

#include <freeradius-devel/util/time.h>
#include <freeradius-devel/util/event.h>
#include <sys/types.h>

Include dependency graph for control.h:

Macros
#define	FR_CONTROL_MAX_MESSAGES (1024)

#define	FR_CONTROL_MAX_SIZE (48)

Typedefs
typedef void(*	fr_control_callback_t) (void const data, size_t data_size, fr_time_t now, void uctx)

typedef enum fr_control_eventset_t	fr_control_eventset_t
	Who defines control plane events.

typedef void(*	fr_control_socket_callback_t) (int sock, fr_time_t now, void *uctx)
	A callback for a message which carries a socket.

typedef struct fr_control_s	fr_control_t
	A one-way control plane.

Enumerations
enum	fr_control_eventset_t : uint16_t { FR_CONTROL_EVENTSET_NETWORK = 0 , FR_CONTROL_EVENTSET_WORKER , FR_CONTROL_EVENTSET_CHANNEL , FR_CONTROL_EVENTSET_COORD , FR_CONTROL_EVENTSET_MAX }
	Who defines control plane events. More...

Functions
void	fr_control_awake (fr_control_t *c)
	Record that the reader of this control plane is running again.

int	fr_control_callback_add (fr_control_t c, fr_control_eventset_t es, uint16_t ev, fr_control_callback_t callback, void uctx))
	Register a callback for a message.

int	fr_control_callback_delete (fr_control_t *c, fr_control_eventset_t es, uint16_t ev)
	Delete a callback for a message.

fr_control_t *	fr_control_create (TALLOC_CTX ctx, fr_event_list_t el, uint16_t slots, uint16_t max_size)
	Create a control-plane signaling path.

bool	fr_control_is_sleeping (fr_control_t *c)
	Check whether the reader of this control plane is blocked.

int	fr_control_message_send (fr_control_t c, fr_control_eventset_t es, uint16_t ev, void const data, size_t data_size)
	Send a control-plane message.

int	fr_control_open (fr_control_t *c)
	Open the control-plane signalling path.

int	fr_control_same_thread (fr_control_t *c)

bool	fr_control_sleeping (fr_control_t *c)
	Record that the reader of this control plane is about to block.

int	fr_control_socket_callback_add (fr_control_t c, fr_control_eventset_t es, uint16_t ev, fr_control_socket_callback_t callback, void uctx))
	Register a callback for a message which carries a socket.

int	fr_control_socket_callback_delete (fr_control_t *c, fr_control_eventset_t es, uint16_t ev)
	Delete a callback for a message which carries a socket.

int	fr_control_socket_send (fr_control_t *c, fr_control_eventset_t es, uint16_t ev, int sock)
	Send a control-plane message carrying a socket.

void	fr_control_wait (fr_control_t *c)
	Wait for a plane control to become readable.

Detailed Description

control-plane signaling

Id: 80ca73676a48929faf5e63b11028c0bae052dd6b

Copyright: 2016 Alan DeKok (aland.nosp@m.@fre.nosp@m.eradi.nosp@m.us.o.nosp@m.rg)

Definition in file control.h.

Macro Definition Documentation

◆ FR_CONTROL_MAX_MESSAGES

#define FR_CONTROL_MAX_MESSAGES (1024)

Definition at line 75 of file control.h.

◆ FR_CONTROL_MAX_SIZE

#define FR_CONTROL_MAX_SIZE (48)

Definition at line 76 of file control.h.

Typedef Documentation

◆ fr_control_callback_t

typedef void(* fr_control_callback_t) (void const *data, size_t data_size, fr_time_t now, void *uctx)

Definition at line 46 of file control.h.

◆ fr_control_eventset_t

typedef enum fr_control_eventset_t fr_control_eventset_t

Who defines control plane events.

Each event set has its own dispatch table on every control, and numbers its own events from zero. A message is addressed by event set and event, so the code behind one set never needs to know what any other set registered.

◆ fr_control_socket_callback_t

typedef void(* fr_control_socket_callback_t) (int sock, fr_time_t now, void *uctx)

A callback for a message which carries a socket.

The callback owns the socket and must close it. The descriptor number is a new one, not the sender's.

Definition at line 53 of file control.h.

◆ fr_control_t

typedef struct fr_control_s fr_control_t

A one-way control plane.

Multiple-producer, single consumer. Messages are copied into a queue the receiver owns, and a byte on a unix socket wakes the receiver. When the socket is full the reader has wakeups it has not consumed, so further bytes are not needed.

Definition at line 45 of file control.h.

Enumeration Type Documentation

◆ fr_control_eventset_t

enum fr_control_eventset_t : uint16_t

Who defines control plane events.

Each event set has its own dispatch table on every control, and numbers its own events from zero. A message is addressed by event set and event, so the code behind one set never needs to know what any other set registered.

Enumerator
FR_CONTROL_EVENTSET_NETWORK	Events the network defines.
FR_CONTROL_EVENTSET_WORKER	Events a worker defines.
FR_CONTROL_EVENTSET_CHANNEL	Events channels define.
FR_CONTROL_EVENTSET_COORD	Events the coordinator defines.
FR_CONTROL_EVENTSET_MAX

Definition at line 62 of file control.h.

Function Documentation

◆ fr_control_awake()

void fr_control_awake ( fr_control_t * c )

Record that the reader of this control plane is running again.

Call this as soon as the reader stops blocking, whatever woke it.

Parameters

[in] c the control structure.

Definition at line 860 of file control.c.

Here is the caller graph for this function:

◆ fr_control_callback_add()

int fr_control_callback_add	(	fr_control_t *	c,
		fr_control_eventset_t	es,
		uint16_t	ev,
		fr_control_callback_t	callback,
		void *	uctx
	)

Register a callback for a message.

Parameters

[in]	c	the control structure
[in]	es	the event set of the message.
[in]	ev	the event, within its event set.
[in]	callback	the callback function
[in]	uctx	the context passed to the callback

Returns

<0 on error
0 on success

Definition at line 659 of file control.c.

Here is the caller graph for this function:

◆ fr_control_callback_delete()

int fr_control_callback_delete	(	fr_control_t *	c,
		fr_control_eventset_t	es,
		uint16_t	ev
	)

Delete a callback for a message.

Parameters

[in]	c	the control structure
[in]	es	the event set of the message.
[in]	ev	the event, within its event set.

Returns

<0 on error
0 on success

Definition at line 786 of file control.c.

◆ fr_control_create()

fr_control_t * fr_control_create	(	TALLOC_CTX *	ctx,
		fr_event_list_t *	el,
		uint16_t	slots,
		uint16_t	max_size
	)

Create a control-plane signaling path.

Parameters

[in]	ctx	the talloc context
[in]	el	the event list for the control socket
[in]	slots	how many messages the socket holds unread.
[in]	max_size	the largest payload a message may carry.

Returns

NULL on error
fr_control_t on success

Definition at line 427 of file control.c.

Here is the caller graph for this function:

◆ fr_control_is_sleeping()

bool fr_control_is_sleeping ( fr_control_t * c )

Check whether the reader of this control plane is blocked.

Call this after pushing work, to decide whether a signal is needed. The fence orders the push before the load. See fr_control_sleeping().

Parameters

[in] c the control structure.

Returns

true if the reader is blocked, and must be signalled.
false if the reader is running, and will find the work itself.

Definition at line 875 of file control.c.

Here is the caller graph for this function:

◆ fr_control_message_send()

int fr_control_message_send	(	fr_control_t *	c,
		fr_control_eventset_t	es,
		uint16_t	ev,
		void const *	data,
		size_t	data_size
	)

Send a control-plane message.

Called from the originating threads. The message is copied into the receiver's queue, then a byte is written to the wakeup socket.

Parameters

[in]	c	the control structure
[in]	es	the event set of this message.
[in]	ev	the event this message signals, within its event set.
[in]	data	the data to write to the control plane
[in]	data_size	the size of the data to write to the control plane.

Returns

<0 on error, including the queue being full.
0 on success

Definition at line 544 of file control.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_control_open()

int fr_control_open ( fr_control_t * c )

Open the control-plane signalling path.

Parameters

[in] c the control-plane to open

Returns

0 on success
-1 on failure

Definition at line 446 of file control.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_control_same_thread()

int fr_control_same_thread ( fr_control_t * c )

Definition at line 881 of file control.c.

Here is the call graph for this function:

◆ fr_control_sleeping()

bool fr_control_sleeping ( fr_control_t * c )

Record that the reader of this control plane is about to block.

Call this before blocking, then check any other work queues one last time. A sender pushes work, then checks this flag. The seq_cst fences stop either side reordering its store after its load, so one of them always sees the other.

Parameters

[in] c the control structure.

Returns

true if messages were serviced, so the caller must not block.
false if the queue was empty.

Definition at line 843 of file control.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_control_socket_callback_add()

int fr_control_socket_callback_add	(	fr_control_t *	c,
		fr_control_eventset_t	es,
		uint16_t	ev,
		fr_control_socket_callback_t	callback,
		void *	uctx
	)

Register a callback for a message which carries a socket.

Socket events are numbered separately from message events within an event set, so the same number may be registered with both this and fr_control_callback_add(). They are sent with fr_control_socket_send().

Parameters

[in]	c	the control structure
[in]	es	the event set of the message.
[in]	ev	the event, within its event set.
[in]	callback	the callback function
[in]	uctx	the context passed to the callback

Returns

<0 on error
0 on success

Definition at line 727 of file control.c.

Here is the caller graph for this function:

◆ fr_control_socket_callback_delete()

int fr_control_socket_callback_delete	(	fr_control_t *	c,
		fr_control_eventset_t	es,
		uint16_t	ev
	)

Delete a callback for a message which carries a socket.

Parameters

[in]	c	the control structure
[in]	es	the event set of the message.
[in]	ev	the event, within its event set.

Returns

<0 on error
0 on success

Definition at line 813 of file control.c.

◆ fr_control_socket_send()

int fr_control_socket_send	(	fr_control_t *	c,
		fr_control_eventset_t	es,
		uint16_t	ev,
		int	sock
	)

Send a control-plane message carrying a socket.

Parameters

[in]	c	the control structure
[in]	es	the event set of this message.
[in]	ev	the event this message signals, within its event set.
[in]	sock	the socket to send.

Returns

<0 on error, including the wakeup socket being full.
0 on success

Definition at line 604 of file control.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_control_wait()

void fr_control_wait ( fr_control_t * c )

Wait for a plane control to become readable.

This is a blocking function so only to be used in rare cases such as waiting for another thread to complete a task before proceeding.

Parameters

[in] c the control structure.

Definition at line 903 of file control.c.

Here is the call graph for this function:

Here is the caller graph for this function:

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ FR_CONTROL_MAX_MESSAGES

◆ FR_CONTROL_MAX_SIZE

Typedef Documentation

◆ fr_control_callback_t

◆ fr_control_eventset_t

◆ fr_control_socket_callback_t

◆ fr_control_t

Enumeration Type Documentation

◆ fr_control_eventset_t

Function Documentation

◆ fr_control_awake()

◆ fr_control_callback_add()

◆ fr_control_callback_delete()

◆ fr_control_create()

◆ fr_control_is_sleeping()

◆ fr_control_message_send()

◆ fr_control_open()

◆ fr_control_same_thread()

◆ fr_control_sleeping()

◆ fr_control_socket_callback_add()

◆ fr_control_socket_callback_delete()

◆ fr_control_socket_send()

◆ fr_control_wait()