Binary IO abstractions for queues of raw packets. More...

Typedefs
typedef void(*	fr_bio_queue_callback_t) (fr_bio_t bio, void packet_ctx, const void *buffer, size_t size)

typedef struct fr_bio_queue_entry_s	fr_bio_queue_entry_t

typedef void(*	fr_bio_queue_saved_t) (fr_bio_t bio, void packet_ctx, const void buffer, size_t size, fr_bio_queue_entry_t queue_ctx)

Functions
fr_bio_t *	fr_bio_queue_alloc (TALLOC_CTX ctx, size_t max_saved, fr_bio_queue_saved_t saved, fr_bio_queue_callback_t sent, fr_bio_queue_callback_t cancel, fr_bio_t next))
	Allocate a packet-based bio. More...

int	fr_bio_queue_cancel (fr_bio_t bio, fr_bio_queue_entry_t queue_ctx)
	Cancel the write for a packet. More...

Detailed Description

Binary IO abstractions for queues of raw packets.

Id: 7e0cb8b9a89ce5b2ead9e4fd780ee90492cdc668

Write packets of data to bios. If a packet is partially read/written, it is cached for later processing.

Copyright: 2024 Network RADIUS SAS (legal.nosp@m.@net.nosp@m.workr.nosp@m.adiu.nosp@m.s.com)

Definition in file queue.h.

Typedef Documentation

◆ fr_bio_queue_callback_t

typedef void(* fr_bio_queue_callback_t) (fr_bio_t *bio, void *packet_ctx, const void *buffer, size_t size)

Definition at line 32 of file queue.h.

◆ fr_bio_queue_entry_t

typedef struct fr_bio_queue_entry_s fr_bio_queue_entry_t

Definition at line 1 of file queue.h.

◆ fr_bio_queue_saved_t

typedef void(* fr_bio_queue_saved_t) (fr_bio_t *bio, void *packet_ctx, const void *buffer, size_t size, fr_bio_queue_entry_t *queue_ctx)

Definition at line 33 of file queue.h.

Function Documentation

◆ fr_bio_queue_alloc()

fr_bio_t* fr_bio_queue_alloc	(	TALLOC_CTX *	ctx,
		size_t	max_saved,
		fr_bio_queue_saved_t	saved,
		fr_bio_queue_callback_t	sent,
		fr_bio_queue_callback_t	cancel,
		fr_bio_t *	next
	)

Allocate a packet-based bio.

This bio assumes that each call to fr_bio_write() is for one packet, and only one packet. If the next bio returns a partial write, or WOULD BLOCK, then information about the packet is cached. Subsequent writes will write the partial data first, and then continue with subsequent writes.

The caller is responsible for not freeing the packet ctx or the packet buffer until either the write has been performed, or the write has been cancelled.

The read() API makes no provisions for reading complete packets. It simply returns whatever the next bio allows. If instead there is a need to read only complete packets, then the next bio should be fr_bio_mem_alloc() with a fr_bio_mem_set_verify()

The read() API may return 0. There may have been data read from an underlying FD, but that data did not make it through the filters of the "next" bios. e.g. Any underlying FD should be put into a "wait for readable" state.

The write() API will return a full write, even if the next layer is blocked. Any underlying FD should be put into a "wait for writeable" state. The packet which was supposed to be written has been cached, and cannot be cancelled as it is partially written. The caller should likely start using another bio for writes. If the caller continues to use the bio, then any subsequent writes will always cache the packets.

Todo:

we need to mark up the bio as "blocked", and then have a write_blocked() API? ugh. or just add bool blocked and bool eof to both read/write bios

Once the underlying FD has become writeable, the caller should call fr_bio_write(bio, NULL, NULL, SIZE_MAX); That will cause the pending packets to be flushed.

The write() API may return that it's written a full packet, in which case it's either completely written to the next bio, or to the pending queue.

The read / write APIs can return WOULD_BLOCK, in which case nothing was done. Any underlying FD should be put into a "wait for writeable" state. Other errors from bios "further down" the chain can also be returned.

Parameters

ctx	the talloc ctx
max_saved	Maximum number of packets to cache. Must be 1..1^17
saved	callback to run when a packet is saved in the pending queue
sent	callback to run when a packet is sent.
cancel	callback to run when a packet is cancelled.
next	the next bio which will perform the underlying reads and writes. NULL on error, memory allocation failed !NULL the bio

Definition at line 397 of file queue.c.

Here is the call graph for this function:

◆ fr_bio_queue_cancel()

int fr_bio_queue_cancel	(	fr_bio_t *	bio,
		fr_bio_queue_entry_t *	item
	)

Cancel the write for a packet.

Cancel one a saved packets, and call the cancel() routine if it exists.

There is no way to cancel all packets. The caller must find the lowest bio in the chain, and shutdown it. e.g. by closing the socket via fr_bio_fd_close(). That function will take care of walking back up the chain, and shutting down each bio.