The FreeRADIUS server $Id: a4e7f8c94e8038b7627bcf52356b7ed15955c1d7 $
Loading...
Searching...
No Matches
Data Structures | Macros | Functions | Variables
control.c File Reference

Control-plane signaling. More...

#include <freeradius-devel/io/atomic_queue.h>
#include <freeradius-devel/io/control.h>
#include <freeradius-devel/util/debug.h>
#include <freeradius-devel/util/strerror.h>
#include <freeradius-devel/util/syserror.h>
#include <freeradius-devel/util/misc.h>
#include <freeradius-devel/util/rand.h>
#include <freeradius-devel/util/stdatomic.h>
#include <fcntl.h>
#include <pthread.h>
#include <stddef.h>
#include <sys/event.h>
#include <sys/socket.h>
#include <poll.h>
+ Include dependency graph for control.c:

Go to the source code of this file.

Data Structures

struct  control_socket_cmsg_t
 Ancillary data for the one socket a datagram may carry. More...
 
struct  fr_control_ctx_t
 
struct  fr_control_eventset_table_t
 The dispatch table for one event set. More...
 
struct  fr_control_header_t
 The header of every message. More...
 
struct  fr_control_s
 The control structure. More...
 
struct  fr_control_s.socket
 
struct  fr_control_socket_ctx_t
 

Macros

#define CACHE_LINE_BYTES   (128)
 
#define CONTROL_RECV_FLAGS   0
 
#define CONTROL_SOCKET_DATAGRAMS   (512)
 
#define CONTROL_SOCKET_MSGS_PER_READ   (64)
 

Functions

static int _control_free (fr_control_t *c)
 Free a control structure.
 
static fr_control_ctx_t const * control_ctx_find (fr_control_t const *c, fr_control_eventset_t es, uint16_t ev)
 Find the callback registered for a message.
 
static size_t control_message_size (fr_control_t const *c)
 The size of one queued message: header and the largest payload.
 
static void control_post_event (UNUSED fr_event_list_t *el, UNUSED fr_time_t now, void *uctx)
 The reader is running again.
 
static int control_pre_event (UNUSED fr_time_t now, UNUSED fr_time_delta_t wake, void *uctx)
 Announce that the reader is about to block, and drain the queue one last time.
 
static void control_read (UNUSED fr_event_list_t *el, int fd, UNUSED int flags, void *uctx)
 Take a batch of datagrams off the wakeup socket, then dispatch every queued message.
 
static unsigned int control_service (fr_control_t *c)
 Dispatch every queued message.
 
static void control_socket_dgram_size_measure (void)
 Measure what one datagram carrying a socket takes up in a socket buffer.
 
static void control_socket_dispatch (fr_control_t *c, struct mmsghdr *mmh, fr_control_header_t const *hdr, fr_time_t now)
 Dispatch one datagram taken off the wakeup socket.
 
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.
 

Variables

static size_t control_socket_dgram_size_actual = 768
 
static pthread_once_t control_socket_dgram_size_once = PTHREAD_ONCE_INIT
 

Detailed Description

Control-plane signaling.

Id
bfff00040856d6db11cbd363c142bed189dd0340

Definition in file control.c.


Data Structure Documentation

◆ control_socket_cmsg_t

struct control_socket_cmsg_t

Ancillary data for the one socket a datagram may carry.

Used on both sides. Aligned as the CMSG macros require, without embedding a cmsghdr, as on Linux that ends in a flexible array and cannot then sit in an array of these.

Definition at line 76 of file control.c.

◆ fr_control_ctx_t

struct fr_control_ctx_t

Definition at line 185 of file control.c.

+ Collaboration diagram for fr_control_ctx_t:
Data Fields
fr_control_callback_t callback the function to call
void * uctx context for the callback

◆ fr_control_eventset_table_t

struct fr_control_eventset_table_t

The dispatch table for one event set.

Definition at line 198 of file control.c.

+ Collaboration diagram for fr_control_eventset_table_t:
Data Fields
fr_control_ctx_t * events callbacks, indexed by event
uint16_t events_num the size of the callback array
fr_control_socket_ctx_t * socket_events callbacks for messages carrying a socket, indexed by event
uint16_t socket_events_num the size of the socket callback array

◆ fr_control_header_t

struct fr_control_header_t

The header of every message.

A message is this header followed by data_size bytes, copied by value into the receiver's queue. The queue places elements 8 byte aligned, and the header is 8 bytes, so callbacks can read their structs straight out of the data.

Definition at line 61 of file control.c.

Data Fields
uint32_t data_size size of the data we're sending
fr_control_eventset_t es event set of this message
uint16_t event event this message signals, within its event set

◆ fr_control_s

struct fr_control_s

The control structure.

Definition at line 211 of file control.c.

+ Collaboration diagram for fr_control_s:
Data Fields
fr_atomic_queue_t * aq the messages, header and data by value.
fr_event_list_t * el our event list
fr_control_eventset_table_t eventsets[FR_CONTROL_EVENTSET_MAX] one table per event set
int fd[2] wakeup socketpair.

[0] is read by the event loop, [1] is written by the senders.

uint16_t max_size the largest payload a message may carry.
bool opened has the control path been opened.
bool same_thread are the two ends in the same thread
atomic_bool sleeping the reader is blocked waiting for a signal.
uint16_t slots messages the queue holds unread.
struct fr_control_s.socket socket

◆ fr_control_s.socket

struct fr_control_s.socket

Definition at line 219 of file control.c.

Data Fields
control_socket_cmsg_t cmsg[CONTROL_SOCKET_MSGS_PER_READ] where their sockets land.
fr_control_header_t hdr[CONTROL_SOCKET_MSGS_PER_READ] where the datagrams land.
struct iovec iov[CONTROL_SOCKET_MSGS_PER_READ] one per datagram.
struct mmsghdr msgs[CONTROL_SOCKET_MSGS_PER_READ] one per datagram, for recvmmsg().

◆ fr_control_socket_ctx_t

struct fr_control_socket_ctx_t

Definition at line 190 of file control.c.

+ Collaboration diagram for fr_control_socket_ctx_t:
Data Fields
fr_control_socket_callback_t callback the function to call
void * uctx context for the callback

Macro Definition Documentation

◆ CACHE_LINE_BYTES

#define CACHE_LINE_BYTES   (128)

Definition at line 51 of file control.c.

◆ CONTROL_RECV_FLAGS

#define CONTROL_RECV_FLAGS   0

Definition at line 182 of file control.c.

◆ CONTROL_SOCKET_DATAGRAMS

#define CONTROL_SOCKET_DATAGRAMS   (512)

Definition at line 94 of file control.c.

◆ CONTROL_SOCKET_MSGS_PER_READ

#define CONTROL_SOCKET_MSGS_PER_READ   (64)

Definition at line 86 of file control.c.

Function Documentation

◆ _control_free()

static int _control_free ( fr_control_t *  c)
static

Free a control structure.

Removes the socket and the idle callbacks from the event loop, and closes both ends.

Parameters
[in]cthe control structure

Definition at line 400 of file control.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ control_ctx_find()

static fr_control_ctx_t const * control_ctx_find ( fr_control_t const *  c,
fr_control_eventset_t  es,
uint16_t  ev 
)
inlinestatic

Find the callback registered for a message.

Parameters
[in]cthe control structure
[in]esthe event set of the message
[in]evthe event, within its event set
Returns
  • NULL if nothing is registered for this event set and event.
  • the callback entry otherwise.

Definition at line 247 of file control.c.

+ Here is the caller graph for this function:

◆ control_message_size()

static size_t control_message_size ( fr_control_t const *  c)
inlinestatic

The size of one queued message: header and the largest payload.

Definition at line 262 of file control.c.

+ Here is the caller graph for this function:

◆ control_post_event()

static void control_post_event ( UNUSED fr_event_list_t *  el,
UNUSED fr_time_t  now,
void *  uctx 
)
static

The reader is running again.

Parameters
[in]uctxthe control structure.

Definition at line 386 of file control.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ control_pre_event()

static int control_pre_event ( UNUSED fr_time_t  now,
UNUSED fr_time_delta_t  wake,
void *  uctx 
)
static

Announce that the reader is about to block, and drain the queue one last time.

The event list runs this when the loop reading this control is about to idle, so every control read by a loop announces itself, whether or not the loop knows about it.

Parameters
[in]uctxthe control structure.
Returns
  • 1 if messages were found, so the loop must not block.
  • 0 if the queue was empty.

Definition at line 375 of file control.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ control_read()

static void control_read ( UNUSED fr_event_list_t *  el,
int  fd,
UNUSED int  flags,
void *  uctx 
)
static

Take a batch of datagrams off the wakeup socket, then dispatch every queued message.

Each datagram is a wakeup, announcing that a message was queued while we were asleep, or a message carying file descriptors in its metdata.

Definition at line 341 of file control.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ control_service()

static unsigned int control_service ( fr_control_t *  c)
inlinestatic

Dispatch every queued message.

Called from the reading thread only.

Parameters
[in]cthe control structure.
Returns
how many messages were dispatched.

Definition at line 274 of file control.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ control_socket_dgram_size_measure()

static void control_socket_dgram_size_measure ( void  )
static

Measure what one datagram carrying a socket takes up in a socket buffer.

Definition at line 109 of file control.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ control_socket_dispatch()

static void control_socket_dispatch ( fr_control_t *  c,
struct mmsghdr *  mmh,
fr_control_header_t const *  hdr,
fr_time_t  now 
)
static

Dispatch one datagram taken off the wakeup socket.

Parameters
[in]cthe control structure.
[in]mmhthe recvmmsg() slot the datagram landed in.
[in]hdrthe datagram, which should be a bare message header.
[in]nowwhen the batch was read.

Definition at line 300 of file control.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ 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]cthe 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]cthe control structure
[in]esthe event set of the message.
[in]evthe event, within its event set.
[in]callbackthe callback function
[in]uctxthe 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]cthe control structure
[in]esthe event set of the message.
[in]evthe 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]ctxthe talloc context
[in]elthe event list for the control socket
[in]slotshow many messages the socket holds unread.
[in]max_sizethe 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]cthe 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]cthe control structure
[in]esthe event set of this message.
[in]evthe event this message signals, within its event set.
[in]datathe data to write to the control plane
[in]data_sizethe 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]cthe 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]cthe 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]cthe control structure
[in]esthe event set of the message.
[in]evthe event, within its event set.
[in]callbackthe callback function
[in]uctxthe 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]cthe control structure
[in]esthe event set of the message.
[in]evthe 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]cthe control structure
[in]esthe event set of this message.
[in]evthe event this message signals, within its event set.
[in]sockthe 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]cthe 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:

Variable Documentation

◆ control_socket_dgram_size_actual

size_t control_socket_dgram_size_actual = 768
static

Definition at line 103 of file control.c.

◆ control_socket_dgram_size_once

pthread_once_t control_socket_dgram_size_once = PTHREAD_ONCE_INIT
static

Definition at line 104 of file control.c.