Skip to contentSkip to conversation

libbpf: Allow callbacks at consumption time

PATCH In review Tamir Duberstein 2 participants 3 messages Jun 12

Subsystems (4)
lore
Share & tools
lore
#0 lore raw

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.

Assisted-by Codex:gpt-5.5

---
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
index b965ad571540..5a87c12bab0b 100644
@@ -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
index b731df19ae69..b6d84297fce7 100644
@@ -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
index 64520684d2cb..df3af61af2e0 100644
@@ -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]>
#1 lore raw
Part 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.

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:

Fixes 4d22ea94ea33 ("libbpf: Add ring__consume_n / ring_buffer__consume_n")

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

#2 lore raw
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.

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 on ringbuf_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.