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_alloc (fr_message_set_t ms, fr_message_t m, size_t actual_packet_size))
	Allocate packet data for a message. More...

fr_message_t *	fr_message_alloc_reserve (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. More...

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

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. More...

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

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

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

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

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

Detailed Description

Inter-thread messaging.

Id: 7206e0084927a678f99326376394966cea8ac4fd

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 1 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_alloc()

fr_message_t* fr_message_alloc	(	fr_message_set_t *	ms,
		fr_message_t *	m,
		size_t	actual_packet_size
	)

Allocate packet data for a message.

The caller will normally call fr_message_reserve() before calling this function, and pass the resulting message 'm' here. If 'm' is NULL, however, this function will call fr_message_reserve() of 'actual_packet_size'. This capability is there for callers who know the size of the message in advance.

Parameters

[in]	ms	the message set
[in]	m	the message message to allocate packet data for
[in]	actual_packet_size	to use

Returns

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

Definition at line 988 of file message.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_message_alloc_reserve()

fr_message_t* fr_message_alloc_reserve	(	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_reserve() with a large buffer, and then read data into the buffer. If the buffer contains multiple packets, the application should call fr_message_alloc_reserve() 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 1077 of file message.c.

Here is the call graph for this function:

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 190 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 242 of file message.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_message_reserve()

fr_message_t* fr_message_reserve	(	fr_message_set_t *	ms,
		size_t	reserve_size
	)

Reserve a message.

A later call to fr_message_alloc() will allocate the correct packet ring buffer size. This call just allocates a message header, and reserves space for the packet.

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_reserve(), and then almost immediately fr_message_alloc(). Multiple calls in series to fr_message_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 934 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
	)

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.

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	(	fr_message_set_t *	ms,
		FILE *	fp
	)

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 1262 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 1238 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 1212 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_alloc()

◆ fr_message_alloc_reserve()

◆ fr_message_done()

◆ fr_message_localize()

◆ fr_message_reserve()

◆ fr_message_set_create()

◆ fr_message_set_debug()

◆ fr_message_set_gc()

◆ fr_message_set_messages_used()