libbpf: Allow callbacks at consumption time
Subsystems (4)
PATCH 1/1 libbpf: Allow callbacks at consumption time
Ring buffer callbacks and contexts are fixed when each ring is added to a manager. Callers that drain records into per-operation state, such as a bounded destination buffer, must therefore keep mutable dispatch state alive for the lifetime of the manager or rebuild it for each operation.
Add bounded manager and per-ring consumption APIs that take a callback and context for one operation. The supplied callback overrides the configured callback without changing it. This also allows managers used only through the new APIs to be created without a setup-time callback.
Make zero-record requests return without invoking callbacks so all bounded consumption APIs preserve their bound.
---
I discussed the desire for this API with Andrii during my time at Meta and more recently with Alexei during Rust Week 2026.
--- tools/lib/bpf/libbpf.h | 56 +++++++++++-- tools/lib/bpf/libbpf.map | 2 + tools/lib/bpf/ringbuf.c | 51 ++++++++++-- tools/testing/selftests/bpf/prog_tests/ringbuf.c | 25 ++++++ .../selftests/bpf/prog_tests/ringbuf_multi.c | 92 ++++++++++++++++++++++ 5 files changed, 214 insertions(+), 12 deletions(-)
tools/lib/bpf/libbpf.h +50 -6
@@ -1471,6 +1471,29 @@ LIBBPF_API int ring_buffer__add(struct ring_buffer *rb, int map_fd, LIBBPF_API int ring_buffer__poll(struct ring_buffer *rb, int timeout_ms); LIBBPF_API int ring_buffer__consume(struct ring_buffer *rb); LIBBPF_API int ring_buffer__consume_n(struct ring_buffer *rb, size_t n); + +/** +* @brief **ring_buffer__consume_n_cb()** consumes up to a requested number of +* records across all registered ring buffer maps without event polling, using +* the provided callback and context for every ring buffer map. +* +* The provided callback and context override the callbacks configured for the +* manager's rings for the duration of this call without changing them. +* **ring_buffer__new()** and **ring_buffer__add()** may receive a NULL callback +* for rings consumed only through this function. +* +* @param rb A ring buffer manager object. +* @param sample_cb Non-NULL callback to invoke for each available record. +* @param ctx Context to pass to *sample_cb*. +* @param n Maximum number of records to consume across all registered ring +* buffer maps. +* @return The number of records consumed (or INT_MAX, whichever is less), or a +* negative error code on failure. +*/ +LIBBPF_API int ring_buffer__consume_n_cb(struct ring_buffer *rb, +ring_buffer_sample_fn sample_cb, +void *ctx,size_t n); + LIBBPF_API int ring_buffer__epoll_fd(const struct ring_buffer *rb);/**
@@ -1546,16 +1569,37 @@ LIBBPF_API int ring__map_fd(const struct ring *r); LIBBPF_API int ring__consume(struct ring *r);/** -* @brief **ring__consume_n()** consumes up to a requested amount of items from -* a ringbuffer without event polling. +* @brief **ring__consume_n()** consumes up to a requested number of records +* from a ring buffer without event polling. * -* @param r A ringbuffer object. -* @param n Maximum amount of items to consume. -* @return The number of items consumed, or a negative number if any of the -* callbacks return an error. +* @param r A ring buffer object. +* @param n Maximum number of records to consume. +* @return The number of records consumed (or INT_MAX, whichever is less), or a +* negative error code on failure. */ LIBBPF_API int ring__consume_n(struct ring *r, size_t n); +/** +* @brief **ring__consume_n_cb()** consumes up to a requested number of records +* from a ring buffer without event polling, using the provided callback and +* context. +* +* The provided callback and context override the callback configured for the +* ring for the duration of this call without changing it. +* **ring_buffer__new()** and **ring_buffer__add()** may receive a NULL callback +* for rings consumed only through this function. +* +* @param r A ring buffer object. +* @param sample_cb Non-NULL callback to invoke for each available record. +* @param ctx Context to pass to *sample_cb*. +* @param n Maximum number of records to consume. +* @return The number of records consumed (or INT_MAX, whichever is less), or a +* negative error code on failure. +*/ +LIBBPF_API int ring__consume_n_cb(struct ring *r, +ring_buffer_sample_fn sample_cb,void *ctx, +size_t n); +struct user_ring_buffer_opts {size_t sz;/* size of this struct, for forward/backward compatibility */ };
tools/lib/bpf/libbpf.map +2 -0
@@ -461,4 +461,6 @@ LIBBPF_1.8.0 { bpf_program__attach_tracing_multi; bpf_program__clone; btf__new_empty_opts; + ring__consume_n_cb; + ring_buffer__consume_n_cb; } LIBBPF_1.7.0;
tools/lib/bpf/ringbuf.c +45 -6
96 lines not on this page · raw message
tools/testing/selftests/bpf/prog_tests/ringbuf.c +25 -0
@@ -397,6 +397,8 @@ static int process_n_sample(void *ctx, void *data, size_t len)struct sample *s = data;ASSERT_EQ (s->value,SAMPLE_VALUE ,"sample_value" ); +if (ctx) + (*(int *)ctx)++;return 0 ; }
@@ -404,6 +406,8 @@ static int process_n_sample(void *ctx, void *data, size_t len)static void ringbuf_n_subtest (void ) {struct test_ringbuf_n_lskel *skel_n; +struct ring *ring; +int cb_cnt =0 ;int err, i; skel_n =test_ringbuf_n_lskel__open ();
@@ -438,6 +442,27 @@ static void ringbuf_n_subtest(void) goto cleanup_ringbuf; } +ring_buffer__free (ringbuf); + ringbuf = +ring_buffer__new (skel_n->maps.ringbuf.map_fd,NULL ,NULL ,NULL ); +if (!ASSERT_OK_PTR (ringbuf,"ring_buffer__new_without_cb" )) + goto cleanup; + +for (i =0 ; i <N_TOT_SAMPLES ; i++) +syscall (__NR_getpgid); + + ring =ring_buffer__ring (ringbuf,0 ); +if (!ASSERT_OK_PTR (ring,"ring_buffer__ring" )) + goto cleanup_ringbuf; + +for (i =0 ; i <N_TOT_SAMPLES ; i += err) { + err =ring__consume_n_cb (ring, process_n_sample, &cb_cnt, +N_SAMPLES ); +if (!ASSERT_EQ (err,N_SAMPLES ,"ring_consume_cb" )) + goto cleanup_ringbuf; + } +ASSERT_EQ (cb_cnt,N_TOT_SAMPLES ,"callback_count" ); + cleanup_ringbuf:ring_buffer__free (ringbuf); cleanup:
tools/testing/selftests/bpf/prog_tests/ringbuf_multi.c +92 -0
110 lines not on this page · raw message
---
base-commit: 30dee2c176e7954f63d1fa3e52d172f30beb9bfb
change-id: 20260611-bpf-ringbuf-callback-4127b8e72882
Best regards,
Signature · 1 line
Tamir Duberstein <[email protected]>
[email protected]
AI reviewPart of this change looks like a bug fix. The early return added to ringbuf_process_ring():
Quoted 12 lines
libbpf: Allow callbacks at consumption time
Ring buffer callbacks and contexts are fixed when each ring is added to a manager. Callers that drain records into per-operation state, such as a bounded destination buffer, must therefore keep mutable dispatch state alive for the lifetime of the manager or rebuild it for each operation.
Add bounded manager and per-ring consumption APIs that take a callback and context for one operation. The supplied callback overrides the configured callback without changing it. This also allows managers used only through the new APIs to be created without a setup-time callback.
Quoted 4 lines
Make zero-record requests return without invoking callbacks so all bounded consumption APIs preserve their bound.
Signed-off-by Tamir Duberstein <[email protected]>
Part of this change looks like a bug fix. The early return added to ringbuf_process_ring():
if (n == 0) return 0;
makes a request for zero records return without consuming or dispatching anything. Before this, the cnt >= n limit was only checked after the sample callback ran, so an n == 0 request still consumed and dispatched one record and violated the requested bound.
That bound-violation behavior came in with the bounded consumption APIs ring_buffer__consume_n() / ring__consume_n() and the n parameter on ringbuf_process_ring(). Should this carry:
---
AI reviewed your patch. Please fix the bug or email reply why it's not a bug.
See: https://github.com/kernel-patches/vmtest/blob/master/ci/claude/README.md
CI run summary: https://github.com/kernel-patches/bpf/actions/runs/27394962126
Quoted 29 lines · On Thu, Jun 11, 2026 at 10:03 PM <[email protected]> wrote:
Quoted 13 lines
libbpf: Allow callbacks at consumption time
Ring buffer callbacks and contexts are fixed when each ring is added to a manager. Callers that drain records into per-operation state, such as a bounded destination buffer, must therefore keep mutable dispatch state alive for the lifetime of the manager or rebuild it for each operation.
Add bounded manager and per-ring consumption APIs that take a callback and context for one operation. The supplied callback overrides the configured callback without changing it. This also allows managers used only through the new APIs to be created without a setup-time callback.
Quoted 4 lines
Make zero-record requests return without invoking callbacks so all bounded consumption APIs preserve their bound.
Signed-off-by Tamir Duberstein <[email protected]>Part of this change looks like a bug fix. The early return added to
ringbuf_process_ring():if (n == 0) return 0;makes a request for zero records return without consuming or dispatching anything. Before this, the cnt >= n limit was only checked after the sample callback ran, so an n == 0 request still consumed and dispatched one record and violated the requested bound.
Quoted 5 lines
That bound-violation behavior came in with the bounded consumption APIs
ring_buffer__consume_n()/ring__consume_n()and the n parameter onringbuf_process_ring(). Should this carry:Fixes 4d22ea94ea33 ("libbpf: Add ring__consume_n / ring_buffer__consume_n")
Thanks. My clanker flagged the same. I will extract this fix into a separate patch in v2.