Inter-thread messaging. More...

#include <freeradius-devel/util/time.h>
#include <freeradius-devel/io/ring_buffer.h>

Include dependency graph for message.h:

Data Structures
struct	fr_message_t

Typedefs
typedef struct fr_message_set_s	fr_message_set_t

typedef enum fr_message_status_t	fr_message_status_t

Enumerations
enum	fr_message_status_t { FR_MESSAGE_FREE = 0 , FR_MESSAGE_USED , FR_MESSAGE_LOCALIZED , FR_MESSAGE_DONE }

Functions
fr_message_t *	fr_message_and_data_alloc (fr_message_set_t *ms, size_t size)
	Reserve and commit a message atomically.

fr_message_t *	fr_message_and_data_commit (fr_message_set_t ms, fr_message_t m, size_t total_size))
	Commit a previously reserved message, allocating exactly total_size bytes of packet data.

fr_message_t *	fr_message_and_data_commit_with_leftover (fr_message_set_t ms, fr_message_t m, size_t actual_packet_size, size_t leftover, size_t reserve_size)
	Allocate packet data for a message, and reserve a new message.

fr_message_t *	fr_message_and_data_reserve (fr_message_set_t *ms, size_t reserve_size)
	Reserve a message.

void	fr_message_and_data_reset (fr_message_set_t ms, fr_message_t m)
	Cancel a reservation made by fr_message_and_data_reserve(), returning the slot to the set.

int	fr_message_done (fr_message_t *m)
	Mark a message as done.

fr_message_t *	fr_message_localize (TALLOC_CTX ctx, fr_message_t m, size_t message_size)
	Localize a message by copying it to local storage.

fr_message_set_t *	fr_message_set_create (TALLOC_CTX *ctx, int num_messages, size_t message_size, size_t ring_buffer_size, bool unlimited_size)
	Create a message set.

void	fr_message_set_debug (FILE fp, fr_message_set_t ms)
	Print debug information about the message set.

void	fr_message_set_gc (fr_message_set_t *ms)
	Garbage collect the message set.

int	fr_message_set_messages_used (fr_message_set_t *ms)
	Count the number of used messages.

Detailed Description

Inter-thread messaging.

Id: d2da6e7e2c4b8fac3fe2ebe98b05819f043d8da3

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

Definition in file message.h.

Data Structure Documentation

◆ fr_message_t

struct fr_message_t

Definition at line 44 of file message.h.

Collaboration diagram for fr_message_t:

Data Fields
uint8_t *	data	pointer to the data in the ring buffer
size_t	data_size	size of the data in the ring buffer
fr_ring_buffer_t *	rb	pointer to the ring buffer
size_t	rb_size	cache-aligned size in the ring buffer
fr_message_status_t	status	free, used, done, etc.
fr_time_t	when	when this message was sent

Typedef Documentation

◆ fr_message_set_t

typedef struct fr_message_set_s fr_message_set_t

Definition at line 35 of file message.h.

◆ fr_message_status_t

typedef enum fr_message_status_t fr_message_status_t

Enumeration Type Documentation

◆ fr_message_status_t

enum fr_message_status_t

Enumerator
FR_MESSAGE_FREE
FR_MESSAGE_USED
FR_MESSAGE_LOCALIZED
FR_MESSAGE_DONE

Definition at line 37 of file message.h.

Function Documentation

◆ fr_message_and_data_alloc()

fr_message_t * fr_message_and_data_alloc	(	fr_message_set_t *	ms,
		size_t	size
	)

Reserve and commit a message atomically.

Combines fr_message_and_data_reserve() and fr_message_and_data_commit() into a single call for callers that know the exact packet size upfront.

Parameters

[in]	ms	the message set
[in]	size	packet size in bytes

Returns

NULL on error
fr_message_t* on success

Definition at line 1108 of file message.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_message_and_data_commit()

fr_message_t * fr_message_and_data_commit	(	fr_message_set_t *	ms,
		fr_message_t *	m,
		size_t	total_size
	)

Commit a previously reserved message, allocating exactly total_size bytes of packet data.

Commits both the message ring slot and the data ring buffer. total_size is the final packet size; it may be less than the original reservation. For streaming reads where m->data_size is already non-zero (leftover bytes from a prior read), total_size must include those bytes.

Parameters

[in]	ms	the message set
[in]	m	the previously reserved message (m is NOT talloc'd)
[in]	total_size	final packet size in bytes

Returns

NULL on error, input message m is left alone
m on success

Definition at line 1051 of file message.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_message_and_data_commit_with_leftover()

fr_message_t * fr_message_and_data_commit_with_leftover	(	fr_message_set_t *	ms,
		fr_message_t *	m,
		size_t	actual_packet_size,
		size_t	leftover,
		size_t	reserve_size
	)

Allocate packet data for a message, and reserve a new message.

This function allocates a previously reserved message, and then reserves a new message.

The application should call fr_message_and_data_reserve() with a large buffer, and then read data into the buffer. If the buffer contains multiple packets, the application should call fr_message_and_data_commit_with_leftover() repeatedly to allocate the full packets, while reserving room for the partial packet.

When the application is determines that there is only one full packet, and one partial packet in the buffer, it should call this function with actual_packet_size, and a large reserve_size. The partial packet will be reserved. If the ring buffer is full, the partial packet will be copied to a new ring buffer.

When the application determines that there are multiple full packets in the buffer, it should call this function with actual_packet_size for each buffer, and reserve_size which reserves all of the data in the buffer. i.e. the full packets + partial packets, which should start off as the original reserve_size.

The application should call this function to allocate each packet, while decreasing reserve_size by each actual_packet_size that was allocated. Once there is only one full and a partial packet in the buffer, it should use a large reserve_size, as above.

The application could just always ecall this function with a large reserve_size, at the cost of substantially more memcpy()s.

Parameters

[in]	ms	the message set
[in]	m	the message message to allocate packet data for
[in]	actual_packet_size	to use
[in]	leftover	"dirty" bytes in the buffer
[in]	reserve_size	to reserve for new message

Returns

NULL on error, and input message m is left alone
fr_message_t* on success. Will always be a new message.

Definition at line 1159 of file message.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_message_and_data_reserve()

fr_message_t * fr_message_and_data_reserve	(	fr_message_set_t *	ms,
		size_t	reserve_size
	)

Reserve a message.

A later call to fr_message_and_data_commit() will commit the reservation. This call just reserves a message header and space for the packet data.

If the caller later decides that the message is not needed, he should call fr_message_free() to free the message.

We assume that the caller will call fr_message_and_data_reserve(), and then almost immediately fr_message_and_data_commit(). Multiple calls in series to fr_message_and_data_reserve() MUST NOT be done. The caller could also just call fr_ring_buffer_alloc(m->rb, size) if they wanted, and then update m->data_size by hand...

The message is returned

Parameters

[in]	ms	the message set
[in]	reserve_size	to reserve

Returns

NULL on error
fr_message_t* on success

Definition at line 973 of file message.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_message_and_data_reset()

void fr_message_and_data_reset	(	fr_message_set_t *	ms,
		fr_message_t *	m
	)

Cancel a reservation made by fr_message_and_data_reserve(), returning the slot to the set.

Both rings are uncommitted at this point (write_offset was not advanced). Clearing the message fields is sufficient: the next reserve overwrites the slot, and the data ring's reserved field is replaced by the new reservation size.

Callers MUST verify m->data_size == 0 before calling this. If a concurrent fr_message_and_data_alloc() aliased this reservation (same ring slot, same data address), m->data_size will be non-zero and the slot is already committed; calling this function in that case corrupts the committed message.

Parameters

[in]	ms	the message set the reservation was made against.
[in]	m	the previously reserved message to cancel.

Definition at line 1026 of file message.c.

Here is the caller graph for this function:

◆ fr_message_done()

int fr_message_done ( fr_message_t * m )

Mark a message as done.

Note that this call is usually done from a thread OTHER than the originator of the message. As such, the message is NOT actually freed. Instead, it is just marked as freed.

Parameters

[in] m the message to make as done.

Returns

<0 on error
0 on success

Definition at line 195 of file message.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_message_localize()

fr_message_t * fr_message_localize	(	TALLOC_CTX *	ctx,
		fr_message_t *	m,
		size_t	message_size
	)

Localize a message by copying it to local storage.

This function "localizes" a message by copying it to local storage. In the case where the recipient of a message has to sit on it for a while, that blocks the originator from cleaning up the message. The recipient can then copy the message to local storage, so that the originator can clean it up.

The localized message is marked as FR_MESSAGE_LOCALIZED, so that the recipient can call the normal fr_message_done() function to free it.

Parameters

[in]	ctx	the talloc context to use for localization
[in]	m	the message to be localized
[in]	message_size	the size of the message, including the fr_message_t

Returns

NULL on allocation error
a newly localized message

Definition at line 247 of file message.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_message_set_create()

fr_message_set_t * fr_message_set_create	(	TALLOC_CTX *	ctx,
		int	num_messages,
		size_t	message_size,
		size_t	ring_buffer_size,
		bool	unlimited_size
	)

Create a message set.

Parameters

[in]	ctx	the context for talloc
[in]	num_messages	size of the initial message array. MUST be a power of 2.
[in]	message_size	the size of each message, INCLUDING fr_message_t, which MUST be at the start of the struct
[in]	ring_buffer_size	of the ring buffer. MUST be a power of 2.
[in]	unlimited_size	allow any message size to be allocated. If false it is limited to ring_buffer_size / 2.

Returns

NULL on error
newly allocated fr_message_set_t on success

Definition at line 127 of file message.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_message_set_debug()

void fr_message_set_debug	(	FILE *	fp,
		fr_message_set_t *	ms
	)

Print debug information about the message set.

Parameters

[in]	ms	the message set
[in]	fp	the FILE where the messages are printed.

Definition at line 1345 of file message.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_message_set_gc()

void fr_message_set_gc ( fr_message_set_t * ms )

Garbage collect the message set.

This function should ONLY be called just before freeing the message set. It is intended only for debugging, and will cause huge latency spikes if used at run time.

Parameters

[in] ms the message set

Definition at line 1321 of file message.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_message_set_messages_used()

int fr_message_set_messages_used ( fr_message_set_t * ms )

Count the number of used messages.

Parameters

[in] ms the message set

Returns

number of used messages

Definition at line 1295 of file message.c.

Here is the call graph for this function:

Here is the caller graph for this function:

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ fr_message_t

Typedef Documentation

◆ fr_message_set_t

◆ fr_message_status_t

Enumeration Type Documentation

◆ fr_message_status_t

Function Documentation

◆ fr_message_and_data_alloc()

◆ fr_message_and_data_commit()

◆ fr_message_and_data_commit_with_leftover()

◆ fr_message_and_data_reserve()

◆ fr_message_and_data_reset()

◆ fr_message_done()

◆ fr_message_localize()

◆ fr_message_set_create()

◆ fr_message_set_debug()

◆ fr_message_set_gc()

◆ fr_message_set_messages_used()