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

2-way channels based on kqueue and atomic queues. More...

#include <freeradius-devel/util/table.h>
#include <freeradius-devel/io/base.h>
#include <freeradius-devel/io/atomic_queue.h>
#include <freeradius-devel/io/control.h>
#include <freeradius-devel/io/message.h>
#include <freeradius-devel/util/dlist.h>
#include <freeradius-devel/util/heap.h>
#include <freeradius-devel/util/log.h>
#include <sys/types.h>
#include <sys/event.h>
+ Include dependency graph for channel.h:

Go to the source code of this file.

Data Structures

struct  fr_channel_callbacks_t
 What the owner of a control plane does with channel lifecycle events. More...
 
struct  fr_channel_data_t
 Channel information which is added to a message. More...
 
union  fr_channel_data_t.__unnamed47__
 
struct  fr_channel_data_t.__unnamed47__.channel
 
struct  fr_channel_data_t.__unnamed47__.live
 
union  fr_channel_data_t.__unnamed49__
 
struct  fr_channel_data_t.__unnamed49__.reply
 
struct  fr_channel_data_t.__unnamed49__.request
 
struct  fr_channel_stats_t
 Statistics for the channel. More...
 

Macros

#define PRIORITY_HIGH   (1 << 15)
 
#define PRIORITY_LOW   (1 << 13)
 
#define PRIORITY_NORMAL   (1 << 14)
 
#define PRIORITY_NOW   (1 << 16)
 

Typedefs

typedef void(* fr_channel_close_t) (fr_channel_t *ch, fr_time_t now, void *uctx)
 Called on a responder when the requestor closes a channel.
 
typedef void(* fr_channel_closed_t) (fr_channel_t *ch, fr_time_t now, void *uctx)
 Called on a requestor when the responder has finished closing a channel.
 
typedef enum fr_channel_control_event_t fr_channel_control_event_t
 Events channels send, in the FR_CONTROL_EVENTSET_CHANNEL event set.
 
typedef void(* fr_channel_open_t) (fr_channel_t *ch, fr_message_set_t *reply_ms, fr_time_t now, void *uctx)
 Called on a responder when a requestor opens a channel to it.
 
typedef void(* fr_channel_recv_callback_t) (fr_channel_t *ch, fr_channel_data_t *cd, void *uctx)
 
typedef struct fr_channel_s fr_channel_t
 A two-way channel (i.e.
 
typedef struct fr_listen_instance_s fr_listen_instance_t
 
typedef struct fr_listen_s fr_listen_t
 

Enumerations

enum  fr_channel_control_event_t : uint16_t {
  FR_CHANNEL_CONTROL_DATA_TO_RESPONDER = 0 ,
  FR_CHANNEL_CONTROL_DATA_TO_REQUESTOR ,
  FR_CHANNEL_CONTROL_DATA_DONE_RESPONDER ,
  FR_CHANNEL_CONTROL_OPEN ,
  FR_CHANNEL_CONTROL_CLOSE ,
  FR_CHANNEL_CONTROL_CLOSE_ACK
}
 Events channels send, in the FR_CONTROL_EVENTSET_CHANNEL event set. More...
 

Functions

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 *frontend, fr_control_t *worker, bool same)
 Create a new channel.
 
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 *ctx)
 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 *ctx)
 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 *cm)
 Send a request message into the channel.
 
int fr_channel_service_kevent (fr_channel_t *ch, fr_control_t *c, struct kevent const *kev)
 
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
 
fr_table_num_sorted_t const channel_signals []
 
size_t channel_signals_len
 

Detailed Description

2-way channels based on kqueue and atomic queues.

Id
0117fc4ee8ac04aefeb3a019b47f781a44ff0a45

Definition in file channel.h.


Data Structure Documentation

◆ fr_channel_callbacks_t

struct fr_channel_callbacks_t

What the owner of a control plane does with channel lifecycle events.

Data arriving on a channel is drained by the channel code itself, through the callbacks set with fr_channel_set_recv_request() and fr_channel_set_recv_reply(). Only the lifecycle events reach the owner. A responder gets open and close, a requestor gets closed. Leave the others NULL.

Definition at line 218 of file channel.h.

+ Collaboration diagram for fr_channel_callbacks_t:
Data Fields
fr_channel_close_t close
fr_channel_closed_t closed
fr_channel_open_t open

◆ fr_channel_data_t

struct fr_channel_data_t

Channel information which is added to a message.

The messages are just for exchanging packet data. The channel data structure is for exchanging requests and replies.

Definition at line 111 of file channel.h.

+ Collaboration diagram for fr_channel_data_t:
Data Fields
union fr_channel_data_t.__unnamed47__ __unnamed__
union fr_channel_data_t.__unnamed49__ __unnamed__
fr_listen_instance_t * inst for tracking packet transport, etc.
fr_message_t m the message header
void * packet_ctx Packet specific context for holding client information, and other proto_* specific information that needs to be passed to the request.
uint32_t priority Priority of this packet.

◆ fr_channel_data_t.__unnamed47__

union fr_channel_data_t.__unnamed47__

Definition at line 114 of file channel.h.

Data Fields
struct fr_channel_data_t.__unnamed47__.channel channel
struct fr_channel_data_t.__unnamed47__.live live

◆ fr_channel_data_t.__unnamed47__.channel

struct fr_channel_data_t.__unnamed47__.channel

Definition at line 129 of file channel.h.

Data Fields
fr_channel_t * ch channel where this messages was received
fr_heap_index_t heap_id for the various queues

◆ fr_channel_data_t.__unnamed47__.live

struct fr_channel_data_t.__unnamed47__.live

Definition at line 119 of file channel.h.

Data Fields
uint64_t ack ACK of the sequence number from the other end.
uint64_t sequence sequence number

◆ fr_channel_data_t.__unnamed49__

union fr_channel_data_t.__unnamed49__

Definition at line 135 of file channel.h.

Data Fields
struct fr_channel_data_t.__unnamed49__.reply reply
struct fr_channel_data_t.__unnamed49__.request request

◆ fr_channel_data_t.__unnamed49__.reply

struct fr_channel_data_t.__unnamed49__.reply

Definition at line 140 of file channel.h.

Data Fields
fr_time_delta_t cpu_time Total CPU time, including predicted work, (only worker -> network).
fr_time_delta_t processing_time Actual processing time for this packet (only worker -> network).
fr_time_t request_time Timestamp of the request packet.

◆ fr_channel_data_t.__unnamed49__.request

struct fr_channel_data_t.__unnamed49__.request

Definition at line 136 of file channel.h.

Data Fields
fr_time_t recv_time time original request was received (network -> worker)

◆ fr_channel_stats_t

struct fr_channel_stats_t

Statistics for the channel.

Definition at line 87 of file channel.h.

+ Collaboration diagram for fr_channel_stats_t:
Data Fields
uint64_t kevents Number of times we've looked at kevents.
fr_time_t last_read_other Last time we successfully read a message from the other the channel.
fr_time_t last_sent_signal The last time when we signaled the other end.
fr_time_t last_write Last write to the channel.
fr_time_delta_t message_interval Interval between messages.
uint64_t outstanding Number of outstanding requests with no reply.
uint64_t packets Number of actual data packets.
uint64_t resignals Number of signals resent.
uint64_t signals Number of kevent signals we've sent.
uint64_t spurious Number of signals we received which found no data waiting.

Macro Definition Documentation

◆ PRIORITY_HIGH

#define PRIORITY_HIGH   (1 << 15)

Definition at line 157 of file channel.h.

◆ PRIORITY_LOW

#define PRIORITY_LOW   (1 << 13)

Definition at line 159 of file channel.h.

◆ PRIORITY_NORMAL

#define PRIORITY_NORMAL   (1 << 14)

Definition at line 158 of file channel.h.

◆ PRIORITY_NOW

#define PRIORITY_NOW   (1 << 16)

Definition at line 156 of file channel.h.

Typedef Documentation

◆ fr_channel_close_t

typedef void(* fr_channel_close_t) (fr_channel_t *ch, fr_time_t now, void *uctx)

Called on a responder when the requestor closes a channel.

The responder calls fr_channel_responder_ack_close() once it has finished with the channel.

Parameters
[in]chthe channel.
[in]nowthe current time.
[in]uctxregistered with the callbacks.

Definition at line 200 of file channel.h.

◆ fr_channel_closed_t

typedef void(* fr_channel_closed_t) (fr_channel_t *ch, fr_time_t now, void *uctx)

Called on a requestor when the responder has finished closing a channel.

Parameters
[in]chthe channel.
[in]nowthe current time.
[in]uctxregistered with the callbacks.

Definition at line 208 of file channel.h.

◆ fr_channel_control_event_t

Events channels send, in the FR_CONTROL_EVENTSET_CHANNEL event set.

The control plane dispatches each to its own callback, see fr_channel_callbacks_add().

◆ fr_channel_open_t

typedef void(* fr_channel_open_t) (fr_channel_t *ch, fr_message_set_t *reply_ms, fr_time_t now, void *uctx)

Called on a responder when a requestor opens a channel to it.

Parameters
[in]chthe new channel.
[in]reply_msthe message set the responder allocates replies from.
[in]nowthe current time.
[in]uctxregistered with the callbacks.

Definition at line 189 of file channel.h.

◆ fr_channel_recv_callback_t

typedef void(* fr_channel_recv_callback_t) (fr_channel_t *ch, fr_channel_data_t *cd, void *uctx)

Definition at line 176 of file channel.h.

◆ fr_channel_t

typedef struct fr_channel_s fr_channel_t

A two-way channel (i.e.

pipe) for exchanging information

While the channels are two-way, they are designed to have a "frontend" writing requests to the channel, and a "worker" reading requests, and writing replies back to the frontend.

Definition at line 41 of file channel.h.

◆ fr_listen_instance_t

Definition at line 48 of file channel.h.

◆ fr_listen_t

typedef struct fr_listen_s fr_listen_t

Definition at line 47 of file channel.h.

Enumeration Type Documentation

◆ fr_channel_control_event_t

Events channels send, in the FR_CONTROL_EVENTSET_CHANNEL event set.

The control plane dispatches each to its own callback, see fr_channel_callbacks_add().

Enumerator
FR_CHANNEL_CONTROL_DATA_TO_RESPONDER 

Requests are queued for the responder.

FR_CHANNEL_CONTROL_DATA_TO_REQUESTOR 

Replies are queued for the requestor.

FR_CHANNEL_CONTROL_DATA_DONE_RESPONDER 

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

Replies may be waiting.

FR_CHANNEL_CONTROL_OPEN 

A requestor has opened a channel to the responder.

FR_CHANNEL_CONTROL_CLOSE 

The requestor is closing the channel.

FR_CHANNEL_CONTROL_CLOSE_ACK 

The responder has finished closing it.

Definition at line 74 of file channel.h.

Function Documentation

◆ 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_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,
struct kevent const *  kev 
)

◆ 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[]
extern

Definition at line 148 of file channel.c.

◆ channel_packet_priority_len

size_t channel_packet_priority_len
extern

Definition at line 154 of file channel.c.

◆ channel_signals

fr_table_num_sorted_t const channel_signals[]
extern

Definition at line 138 of file channel.c.

◆ channel_signals_len

size_t channel_signals_len
extern

Definition at line 146 of file channel.c.