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

Two-way thread-safe channels. More...

#include <freeradius-devel/io/channel.h>
#include <freeradius-devel/util/debug.h>
#include <freeradius-devel/util/stdatomic.h>
+ Include dependency graph for channel.c:

Go to the source code of this file.

Data Structures

struct  fr_channel_control_t
 The payload of every channel control message. More...
 
struct  fr_channel_end_t
 One end of a channel. More...
 
struct  fr_channel_hooks_t
 The callbacks one control plane's owner registered for channel events. More...
 
struct  fr_channel_s
 A full channel, which consists of two ends. More...
 

Macros

#define ATOMIC_QUEUE_SIZE   (1024)
 Size of the atomic queues.
 
#define IALPHA   (8)
 
#define MPRINT(...)
 
#define RTT(_old, _new)   fr_time_delta_wrap((fr_time_delta_unwrap(_new) + (fr_time_delta_unwrap(_old) * (IALPHA - 1))) / IALPHA)
 

Typedefs

typedef struct fr_channel_s fr_channel_t
 

Enumerations

enum  fr_channel_direction_t : uint8_t {
  TO_RESPONDER = 0 ,
  TO_REQUESTOR = 1
}
 

Functions

static void channel_close (void const *data, size_t data_size, fr_time_t now, void *uctx)
 The requestor is closing a channel to us.
 
static void channel_close_ack (void const *data, size_t data_size, fr_time_t now, void *uctx)
 The responder has finished closing a channel we asked it to close.
 
static void channel_data_done_responder (void const *data, size_t data_size, fr_time_t now, void *uctx)
 The responder has serviced its requests, and says how many it has seen.
 
static void channel_data_to_requestor (void const *data, size_t data_size, UNUSED fr_time_t now, void *uctx)
 The responder has queued replies for the requestor.
 
static void channel_data_to_responder (void const *data, size_t data_size, UNUSED fr_time_t now, void *uctx)
 The requestor has queued requests for the responder.
 
static void channel_drain_replies (fr_channel_t *ch)
 Drain the replies queued for the requestor.
 
static void channel_drain_requests (fr_channel_t *ch)
 Drain the requests queued for the responder.
 
static void channel_message_unpack (fr_channel_control_t *cc, void const *data, NDEBUG_UNUSED size_t data_size)
 Unpack the payload of a channel control message.
 
static void channel_open (void const *data, size_t data_size, fr_time_t now, void *uctx)
 A requestor has opened a channel to us.
 
bool fr_channel_active (fr_channel_t *ch)
 Check if a channel is active.
 
int fr_channel_callbacks_add (fr_control_t *c, fr_channel_callbacks_t const *callbacks, void *uctx)
 Register the owner's channel callbacks on its control plane.
 
fr_channel_t * fr_channel_create (TALLOC_CTX *ctx, fr_control_t *requestor, fr_control_t *responder, bool same)
 Create a new channel.
 
static int fr_channel_data_ready (fr_channel_t *ch, fr_time_t when, fr_channel_end_t *end, fr_channel_control_event_t ev)
 Send a message via a kq user signal.
 
int fr_channel_null_reply (fr_channel_t *ch)
 Don't send a reply message into the channel.
 
bool fr_channel_recv_reply (fr_channel_t *ch)
 Receive a reply message from the channel.
 
bool fr_channel_recv_request (fr_channel_t *ch)
 Receive a request message from the channel.
 
fr_channel_stats_t const * fr_channel_requestor_stats (fr_channel_t const *ch)
 Statistics for the requestor's end of a channel.
 
void fr_channel_requestor_uctx_add (fr_channel_t *ch, void *uctx)
 Add network-specific data to a channel.
 
void * fr_channel_requestor_uctx_get (fr_channel_t *ch)
 Get network-specific data from a channel.
 
int fr_channel_responder_ack_close (fr_channel_t *ch)
 Acknowledge that the channel is closing.
 
unsigned int fr_channel_responder_discard (fr_channel_t *ch)
 Discard any requests the requestor queued but we never received.
 
fr_channel_stats_t const * fr_channel_responder_stats (fr_channel_t const *ch)
 Statistics for the responder's end of a channel.
 
void fr_channel_responder_uctx_add (fr_channel_t *ch, void *uctx)
 Add responder-specific data to a channel.
 
void * fr_channel_responder_uctx_get (fr_channel_t *ch)
 Get responder-specific data from a channel.
 
int fr_channel_send_reply (fr_channel_t *ch, fr_channel_data_t *cd)
 Send a reply message into the channel.
 
int fr_channel_send_request (fr_channel_t *ch, fr_channel_data_t *cd)
 Send a request message into the channel.
 
int fr_channel_service_kevent (fr_channel_t *ch, fr_control_t *c, UNUSED struct kevent const *kev)
 Service a control-plane event.
 
int fr_channel_set_recv_reply (fr_channel_t *ch, fr_channel_recv_callback_t recv_reply, void *uctx)
 
int fr_channel_set_recv_request (fr_channel_t *ch, fr_channel_recv_callback_t recv_request, void *uctx)
 
int fr_channel_signal_open (fr_channel_t *ch, fr_message_set_t *reply_ms)
 Send a channel to a responder.
 
int fr_channel_signal_responder_close (fr_channel_t *ch)
 Signal a responder that the channel is closing.
 
void fr_channel_stats_log (fr_channel_t const *ch, fr_log_t const *log, char const *file, int line)
 

Variables

fr_table_num_sorted_t const channel_packet_priority []
 
size_t channel_packet_priority_len = NUM_ELEMENTS(channel_packet_priority)
 
fr_table_num_sorted_t const channel_signals []
 
size_t channel_signals_len = NUM_ELEMENTS(channel_signals)
 

Detailed Description

Two-way thread-safe channels.

Id
693d7f9ff179420537b600091c13173c70ef1eda

Definition in file channel.c.


Data Structure Documentation

◆ fr_channel_control_t

struct fr_channel_control_t

The payload of every channel control message.

Which event it is comes from the control message, not from the payload.

Definition at line 79 of file channel.c.

+ Collaboration diagram for fr_channel_control_t:
Data Fields
uint64_t ack the sender's ack sequence, for data done.
fr_channel_t * ch the channel
fr_message_set_t * reply_ms the reply message set, for open only.

◆ fr_channel_end_t

struct fr_channel_end_t

One end of a channel.

Consists of a kqueue descriptor, and an atomic queue. The atomic queue is there to get bulk data through, because it's more efficient than pushing 1M+ events per second through a kqueue.

Definition at line 99 of file channel.c.

+ Collaboration diagram for fr_channel_end_t:
Data Fields
uint64_t ack Sequence number of the other end.
atomic_bool active Whether the channel is active.
fr_atomic_queue_t * aq The queue of messages - visible only to this channel.
fr_control_t * control The control plane we signal this end through.
fr_channel_direction_t direction Use for debug messages.
fr_channel_recv_callback_t recv callback for receiving messages
void * recv_uctx context for receiving messages
uint64_t sequence Sequence number for this channel.
uint64_t sequence_at_last_signal When we last signaled.
fr_channel_stats_t stats channel statistics
uint64_t their_view_of_my_sequence Should be clear.
void * uctx Worker context.

◆ fr_channel_hooks_t

struct fr_channel_hooks_t

The callbacks one control plane's owner registered for channel events.

Definition at line 87 of file channel.c.

+ Collaboration diagram for fr_channel_hooks_t:
Data Fields
fr_channel_callbacks_t cb what the owner does with each event
fr_control_t * control the control plane these were registered on
void * uctx passed to each callback

◆ fr_channel_s

struct fr_channel_s

A full channel, which consists of two ends.

A channel consists of an I/O identifier that can be placed in kequeue and an atomic queue in each direction to allow for bidirectional communication.

Definition at line 129 of file channel.c.

+ Collaboration diagram for fr_channel_s:
Data Fields
fr_time_delta_t cpu_time Total time used by the responder for this channel.
fr_channel_end_t end[2] Two ends of the channel.
fr_time_delta_t processing_time Time spent by the responder processing requests.
bool same_thread are both ends in the same thread?

Macro Definition Documentation

◆ ATOMIC_QUEUE_SIZE

#define ATOMIC_QUEUE_SIZE   (1024)

Size of the atomic queues.

The queue reader MUST service the queue occasionally, otherwise the writer will not be able to write. If it's too low, the writer will fail. If it's too high, it will unnecessarily use memory. So we're better off putting it on the high side.

The reader SHOULD service the queues at inter-packet latency. i.e. at 1M pps, the queue will get serviced every microsecond.

Definition at line 73 of file channel.c.

◆ IALPHA

#define IALPHA   (8)

Definition at line 256 of file channel.c.

◆ MPRINT

#define MPRINT (   ...)

Definition at line 42 of file channel.c.

◆ RTT

#define RTT (   _old,
  _new 
)    fr_time_delta_wrap((fr_time_delta_unwrap(_new) + (fr_time_delta_unwrap(_old) * (IALPHA - 1))) / IALPHA)

Definition at line 257 of file channel.c.

Typedef Documentation

◆ fr_channel_t

typedef struct fr_channel_s fr_channel_t

Definition at line 122 of file channel.c.

Enumeration Type Documentation

◆ fr_channel_direction_t

Enumerator
TO_RESPONDER 
TO_REQUESTOR 

Definition at line 45 of file channel.c.

Function Documentation

◆ channel_close()

static void channel_close ( void const *  data,
size_t  data_size,
fr_time_t  now,
void *  uctx 
)
static

The requestor is closing a channel to us.

Definition at line 745 of file channel.c.

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

◆ channel_close_ack()

static void channel_close_ack ( void const *  data,
size_t  data_size,
fr_time_t  now,
void *  uctx 
)
static

The responder has finished closing a channel we asked it to close.

Definition at line 759 of file channel.c.

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

◆ channel_data_done_responder()

static void channel_data_done_responder ( void const *  data,
size_t  data_size,
fr_time_t  now,
void *  uctx 
)
static

The responder has serviced its requests, and says how many it has seen.

Only sent by the responder. Replies may be waiting, so drain them. First compare their ACK to the last sequence we sent, and if they have not seen our latest, signal the responder to wake up.

Definition at line 671 of file channel.c.

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

◆ channel_data_to_requestor()

static void channel_data_to_requestor ( void const *  data,
size_t  data_size,
UNUSED fr_time_t  now,
void *  uctx 
)
static

The responder has queued replies for the requestor.

Must arrive on the requestor's control plane.

Definition at line 653 of file channel.c.

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

◆ channel_data_to_responder()

static void channel_data_to_responder ( void const *  data,
size_t  data_size,
UNUSED fr_time_t  now,
void *  uctx 
)
static

The requestor has queued requests for the responder.

Must arrive on the responder's control plane.

Definition at line 637 of file channel.c.

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

◆ channel_drain_replies()

static void channel_drain_replies ( fr_channel_t *  ch)
inlinestatic

Drain the replies queued for the requestor.

Runs on the requestor's thread, see channel_drain_requests().

Definition at line 624 of file channel.c.

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

◆ channel_drain_requests()

static void channel_drain_requests ( fr_channel_t *  ch)
inlinestatic

Drain the requests queued for the responder.

Runs on the responder's thread, so a signal which finds nothing is counted in the responder's own stats. Each end's stats are only ever written by that end's thread.

Definition at line 611 of file channel.c.

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

◆ channel_message_unpack()

static void channel_message_unpack ( fr_channel_control_t *  cc,
void const *  data,
NDEBUG_UNUSED size_t  data_size 
)
inlinestatic

Unpack the payload of a channel control message.

Definition at line 599 of file channel.c.

+ Here is the caller graph for this function:

◆ channel_open()

static void channel_open ( void const *  data,
size_t  data_size,
fr_time_t  now,
void *  uctx 
)
static

A requestor has opened a channel to us.

Definition at line 731 of file channel.c.

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

◆ fr_channel_active()

bool fr_channel_active ( fr_channel_t *  ch)

Check if a channel is active.

A channel may be closed by either end. If so, it stays alive (but inactive) until both ends acknowledge the close.

Parameters
[in]chthe channel
Returns
  • false the channel is closing.
  • true the channel is active

Definition at line 850 of file channel.c.

+ Here is the caller graph for this function:

◆ fr_channel_callbacks_add()

int fr_channel_callbacks_add ( fr_control_t *  c,
fr_channel_callbacks_t const *  callbacks,
void *  uctx 
)

Register the owner's channel callbacks on its control plane.

Call before fr_control_open(). Every channel event gets its own entry in the FR_CONTROL_EVENTSET_CHANNEL event set, so the control plane dispatches straight to the handler for that event.

Parameters
[in]cthe control plane channels will signal.
[in]callbackswhat the owner does with each event. Copied.
[in]uctxpassed to each callback.
Returns
  • <0 on error
  • 0 on success

Definition at line 784 of file channel.c.

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

◆ fr_channel_create()

fr_channel_t * fr_channel_create ( TALLOC_CTX *  ctx,
fr_control_t *  requestor,
fr_control_t *  responder,
bool  same 
)

Create a new channel.

Parameters
[in]ctxThe talloc_ctx to allocate channel data in.
[in]requestorcontrol plane.
[in]respondercontrol plane.
[in]samewhether or not the channel is for the same thread
Returns
  • NULL on error
  • channel on success

Definition at line 167 of file channel.c.

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

◆ fr_channel_data_ready()

static int fr_channel_data_ready ( fr_channel_t *  ch,
fr_time_t  when,
fr_channel_end_t *  end,
fr_channel_control_event_t  ev 
)
static

Send a message via a kq user signal.

Note that the caller doesn't care about data in the event, that is sent via the atomic queue. The kevent code takes care of delivering the signal once, even if it's sent by multiple requestor threads.

The thread watching the KQ knows which end it is. So when it gets the signal (and the channel pointer) it knows to look at end[0] or end[1]. We also send which end in 'which' (0, 1) to further help the recipient.

Parameters
[in]chthe channel.
[in]whenthe data was ready. Typically taken from the message.
[in]endof the channel that the message was written to.
[in]evthe event to send.
Returns
  • <0 on error
  • 0 on success

Definition at line 238 of file channel.c.

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

◆ fr_channel_null_reply()

int fr_channel_null_reply ( fr_channel_t *  ch)

Don't send a reply message into the channel.

The message should be the one we received from the network.

Parameters
[in]chthe channel on which we're dropping a packet
Returns
  • <0 on error
  • 0 on success

Definition at line 585 of file channel.c.

+ Here is the caller graph for this function:

◆ fr_channel_recv_reply()

bool fr_channel_recv_reply ( fr_channel_t *  ch)

Receive a reply message from the channel.

Parameters
[in]chthe channel to read data from.
Returns
  • true if there was a message received
  • false if there are no more messages

Definition at line 354 of file channel.c.

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

◆ fr_channel_recv_request()

bool fr_channel_recv_request ( fr_channel_t *  ch)

Receive a request message from the channel.

Parameters
[in]chthe channel
Returns
  • true if there was a message received
  • false if there are no more messages

Definition at line 418 of file channel.c.

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

◆ fr_channel_requestor_stats()

fr_channel_stats_t const * fr_channel_requestor_stats ( fr_channel_t const *  ch)

Statistics for the requestor's end of a channel.

Signals the requestor sent, and signals it received which found nothing.

Definition at line 1056 of file channel.c.

+ Here is the caller graph for this function:

◆ fr_channel_requestor_uctx_add()

void fr_channel_requestor_uctx_add ( fr_channel_t *  ch,
void *  uctx 
)

Add network-specific data to a channel.

Parameters
[in]chThe channel.
[in]uctxThe context to add.

Definition at line 970 of file channel.c.

+ Here is the caller graph for this function:

◆ fr_channel_requestor_uctx_get()

void * fr_channel_requestor_uctx_get ( fr_channel_t *  ch)

Get network-specific data from a channel.

Parameters
[in]chThe channel.

Definition at line 982 of file channel.c.

+ Here is the caller graph for this function:

◆ fr_channel_responder_ack_close()

int fr_channel_responder_ack_close ( fr_channel_t *  ch)

Acknowledge that the channel is closing.

Parameters
[in]chThe channel.
Returns
  • <0 on error
  • 0 on success

Definition at line 916 of file channel.c.

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

◆ fr_channel_responder_discard()

unsigned int fr_channel_responder_discard ( fr_channel_t *  ch)

Discard any requests the requestor queued but we never received.

The messages belong to the requestor's message set, and it cannot reclaim them until they are marked done. A responder that closes with requests still in the queue would strand them there, and with them the memory they were allocated from.

Parameters
[in]chto discard the queued requests of.
Returns
the number of requests discarded.

Definition at line 895 of file channel.c.

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

◆ fr_channel_responder_stats()

fr_channel_stats_t const * fr_channel_responder_stats ( fr_channel_t const *  ch)

Statistics for the responder's end of a channel.

Definition at line 1063 of file channel.c.

+ Here is the caller graph for this function:

◆ fr_channel_responder_uctx_add()

void fr_channel_responder_uctx_add ( fr_channel_t *  ch,
void *  uctx 
)

Add responder-specific data to a channel.

Parameters
[in]chThe channel.
[in]uctxThe context to add.

Definition at line 945 of file channel.c.

+ Here is the caller graph for this function:

◆ fr_channel_responder_uctx_get()

void * fr_channel_responder_uctx_get ( fr_channel_t *  ch)

Get responder-specific data from a channel.

Parameters
[in]chThe channel.

Definition at line 957 of file channel.c.

+ Here is the caller graph for this function:

◆ fr_channel_send_reply()

int fr_channel_send_reply ( fr_channel_t *  ch,
fr_channel_data_t *  cd 
)

Send a reply message into the channel.

The message should be initialized, other than "sequence" and "ack".

Parameters
[in]chthe channel to send the reply on.
[in]cdthe message to send
Returns
  • <0 on error
  • 0 on success

Definition at line 457 of file channel.c.

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

◆ fr_channel_send_request()

int fr_channel_send_request ( fr_channel_t *  ch,
fr_channel_data_t *  cd 
)

Send a request message into the channel.

The message should be initialized, other than "sequence" and "ack".

This function automatically calls the recv_reply callback if there is a reply.

Parameters
[in]chthe channel to send the request on.
[in]cdthe message to send.
Returns
  • <0 on error
  • 0 on success

Definition at line 271 of file channel.c.

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

◆ fr_channel_service_kevent()

int fr_channel_service_kevent ( fr_channel_t *  ch,
fr_control_t *  c,
UNUSED struct kevent const *  kev 
)

Service a control-plane event.

The channels use control planes for internal signaling. Note that the caller does NOT pass the channel into this function. Instead, the channel is taken from the kevent.

Parameters
[in]chThe channel to service.
[in]cThe control plane on which we received the kev.
[in]kevThe kevent data, should get passed to the control plane.
Returns
  • <0 on error
  • 0 on success

Definition at line 826 of file channel.c.

+ Here is the caller graph for this function:

◆ fr_channel_set_recv_reply()

int fr_channel_set_recv_reply ( fr_channel_t *  ch,
fr_channel_recv_callback_t  recv_reply,
void *  uctx 
)

Definition at line 990 of file channel.c.

+ Here is the caller graph for this function:

◆ fr_channel_set_recv_request()

int fr_channel_set_recv_request ( fr_channel_t *  ch,
fr_channel_recv_callback_t  recv_request,
void *  uctx 
)

Definition at line 998 of file channel.c.

+ Here is the caller graph for this function:

◆ fr_channel_signal_open()

int fr_channel_signal_open ( fr_channel_t *  ch,
fr_message_set_t *  reply_ms 
)

Send a channel to a responder.

Parameters
[in]chThe channel.
[in]reply_msThe message set the responder allocates replies from.
Returns
  • <0 on error
  • 0 on success

Definition at line 1013 of file channel.c.

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

◆ fr_channel_signal_responder_close()

int fr_channel_signal_responder_close ( fr_channel_t *  ch)

Signal a responder that the channel is closing.

Parameters
[in]chThe channel.
Returns
  • <0 on error
  • 0 on success

Definition at line 862 of file channel.c.

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

◆ fr_channel_stats_log()

void fr_channel_stats_log ( fr_channel_t const *  ch,
fr_log_t const *  log,
char const *  file,
int  line 
)

Definition at line 1025 of file channel.c.

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

Variable Documentation

◆ channel_packet_priority

fr_table_num_sorted_t const channel_packet_priority[]
Initial value:
= {
{ L("high"), PRIORITY_HIGH },
{ L("low"), PRIORITY_LOW },
{ L("normal"), PRIORITY_NORMAL },
{ L("now"), PRIORITY_NOW }
}
#define L(_str)
Helper for initialising arrays of string literals.
Definition build.h:245
#define PRIORITY_NORMAL
Definition channel.h:158
#define PRIORITY_NOW
Definition channel.h:156
#define PRIORITY_HIGH
Definition channel.h:157
#define PRIORITY_LOW
Definition channel.h:159

Definition at line 148 of file channel.c.

◆ channel_packet_priority_len

size_t channel_packet_priority_len = NUM_ELEMENTS(channel_packet_priority)

Definition at line 154 of file channel.c.

◆ channel_signals

fr_table_num_sorted_t const channel_signals[]
Initial value:
= {
{ L("close"), FR_CHANNEL_CONTROL_CLOSE },
{ L("close-ack"), FR_CHANNEL_CONTROL_CLOSE_ACK },
{ L("data-done-responder"), FR_CHANNEL_CONTROL_DATA_DONE_RESPONDER },
{ L("data-to-requestor"), FR_CHANNEL_CONTROL_DATA_TO_REQUESTOR },
{ L("data-to-responder"), FR_CHANNEL_CONTROL_DATA_TO_RESPONDER },
{ L("open"), FR_CHANNEL_CONTROL_OPEN },
}
@ FR_CHANNEL_CONTROL_OPEN
A requestor has opened a channel to the responder.
Definition channel.h:79
@ FR_CHANNEL_CONTROL_DATA_TO_REQUESTOR
Replies are queued for the requestor.
Definition channel.h:76
@ FR_CHANNEL_CONTROL_DATA_DONE_RESPONDER
The responder has serviced its requests, and says how many it has seen.
Definition channel.h:77
@ FR_CHANNEL_CONTROL_CLOSE_ACK
The responder has finished closing it.
Definition channel.h:81
@ FR_CHANNEL_CONTROL_CLOSE
The requestor is closing the channel.
Definition channel.h:80
@ FR_CHANNEL_CONTROL_DATA_TO_RESPONDER
Requests are queued for the responder.
Definition channel.h:75

Definition at line 138 of file channel.c.

◆ channel_signals_len

size_t channel_signals_len = NUM_ELEMENTS(channel_signals)

Definition at line 146 of file channel.c.