ring_buf_yield.c File Reference

Implementation of ring buffer yielding functions. More...

#include "ring_buf_yield.h"

Include dependency graph for ring_buf_yield.c:

Go to the source code of this file.

Functions
int	ring_buf_get_claim_yield (struct ring_buf *buf, ring_buf_size_t size, int yield(void *space, int index, void *extra), void *extra)
	Claims ring buffer space and yields it to a callback function.
int	ring_buf_get_yield (struct ring_buf *buf, void *data, ring_buf_size_t size, int yield(void *data, int index, void *extra), void *extra)
	Copies buffer space and yields it to a callback function.

Detailed Description

Implementation of ring buffer yielding functions.

This file contains the definitions for functions that allow yielding of ring buffer space to a callback function.

Copyright

2024, 2025, Roy Ratcliffe, Northumberland, United Kingdom

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Definition in file ring_buf_yield.c.

Function Documentation

ring_buf_get_claim_yield()

int ring_buf_get_claim_yield	(	struct ring_buf *	buf,
		ring_buf_size_t	size,
		int	yieldvoid *space, int index, void *extra,
		void *	extra
	)

Claims ring buffer space and yields it to a callback function.

This function repeatedly claims buffer spans of the specified size and passes them to the provided yield function until no more spans (of the given size) can be obtained. The yield function is called with the obtained buffer span, a zero-based index indicating the order of the span, and an extra context pointer.

Parameters

buf	Pointer to the ring buffer.
size	Buffer space size to claim for each yield.
yield	Function to call with the claimed buffer span.
extra	Extra context pointer to pass to the yield function.

Returns

The number of yielded spans, or the yield result if the latter is not -EAGAIN.

Note

The yield function should return -EAGAIN to continue yielding, or any other value to terminate the yielding process.

This function does not acknowledge the claimed space; the caller is responsible for acknowledging it as needed.

This function is useful for processing data in a ring buffer in chunks. Iteration stops if the ring buffer runs out of claimable space of the specified size. This includes the case where the buffer is empty, or if the remaining contiguous space is smaller than the requested chunk size.

Definition at line 34 of file ring_buf_yield.c.

ring_buf_get_yield()

int ring_buf_get_yield	(	struct ring_buf *	buf,
		void *	data,
		ring_buf_size_t	size,
		int	yieldvoid *data, int index, void *extra,
		void *	extra
	)

Copies buffer space and yields it to a callback function.

This function repeatedly copies discontiguous spans from the ring buffer's claim space of the specified size and passes it to the provided yield function until it exhausts the claim zone. The yield function is called with the copied buffer space, an index indicating the order of the space, and an extra context pointer.

Parameters

buf	Pointer to the ring buffer.
data	Pointer to the space to fill. Can be NULL if the data is not needed.
size	Size of the space to fill.
yield	Function to call with the filled buffer space.
extra	Extra context pointer to pass to the yield function.

Returns

The number of yields, or the yield result if it is not -EAGAIN.

Definition at line 53 of file ring_buf_yield.c.