libbpf-ruby 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 380f5e9be54f279c6211b57cd8401ce93c917203e5b5d6737761b93e67504f18
-  data.tar.gz: a1e72cbcde4b31a7d9cf2dbb72fe171638f1b129347026ffc141dbff475f8f36
+  metadata.gz: b8277f696bfd122d3366718fa451b9213aa939ac293a435e07467f41a6f32d0b
+  data.tar.gz: cac0061ddd89bd4b8c87156d904d09bd722f3ad440cce5de4e3115ded32d1eee
 SHA512:
-  metadata.gz: 5c1fc35aaf5677ccb43ad57abc45905db21b0ef1f74d69df3e3c4cde7855bfd93b6ddb59a9ddd632b21e2aabc236b8e4bd7b069b1c34c0e7293f47db37e9dcdb
-  data.tar.gz: 9d5a11b204cc0feff9dd41d97e225ac376f669d5b604dc427b320ac203f38c98b898ace5e781c704239afbc1298566ab08ae99cbe62e08324ecb924de9a21098
+  metadata.gz: 2a8f61134a7cea49cd875ee5c76059889f438af05cc3ca8c202ca7a2df95148f3a4f756be39ac05b1ce7002b40c9f9ce3f3c7d237f558180a7ed780e8ffd2e45
+  data.tar.gz: 1bc728b63b499f5f3de64e663ad94be6e7a6692cb09886806a857fcba18caa515856d8595e4fe188eb2bbedec95d2c3e2b45192febb929d6e29c5416bfb4117b

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 ## [Unreleased]
 
+## [0.2.0] - 2026-08-09
+
+- Release the GVL during blocking libbpf calls
+- Add `Program#attach_perf_event`
+- Add `Program#attach_cgroup`
+- Add `Program#attach_raw_tracepoint`
+- Add `Program#attach_tracepoint`
+- Add `Program#attach_uprobe`
+- Add `Program#attach_kprobe`
+- Add `Program#attach_tcx`
+- Add `Program#attach_xdp`
+- Add `Program` and `Link` classes with `Program#attach`
+
 ## [0.1.1] - 2026-07-05
 
 - Skip native extension compilation on non-Linux platforms

data/README.md

@@ -33,13 +33,21 @@ require "socket"
 
 object = LibBPFRuby::Object.new("my_program.bpf.o")
 
-program_fd = object.program_fd("my_program")
+# Map updates and reuseport-based load balancing:
 map_fd = object.map_fd("my_map")
-
 LibBPFRuby.map_update(map_fd, [0].pack("L"), [42].pack("L"))
 
 listening_socket = TCPServer.new(3000)
-LibBPFRuby.attach_reuseport(listening_socket, program_fd)
+LibBPFRuby.attach_reuseport(listening_socket, object.program_fd("my_reuseport_program"))
+
+# First-class Programs and Links for every other hook:
+lo_ifindex = File.read("/sys/class/net/lo/ifindex").to_i
+xdp_link = object.program("my_xdp_program").attach_xdp(lo_ifindex)
+kprobe_link = object.program("my_kprobe_program").attach_kprobe("do_nanosleep")
+tp_link = object.program("my_tracepoint_program").attach_tracepoint("syscalls", "sys_enter_read")
+
+# Detach explicitly, or let GC destroy the link:
+xdp_link.detach
 ```
 
 ## Development

data/ext/libbpf_ruby/extconf.rb

@@ -4,6 +4,7 @@ require "mkmf"
 
 if RUBY_PLATFORM.include?("linux") && have_library("bpf") && have_header("bpf/libbpf.h")
   append_cflags("-fvisibility=hidden")
+  have_func("bpf_program__attach_tcx", "bpf/libbpf.h")
   create_makefile("libbpf_ruby/libbpf_ruby")
 else
   File.write("Makefile", "all install clean:\n\t@true\n")

data/ext/libbpf_ruby/libbpf_ruby.c

@@ -7,10 +7,28 @@ static int libbpf_ruby_print(enum libbpf_print_level level, const char *format,
   return 0;
 }
 
+static VALUE rb_cLibBPFRubyProgram;
+static VALUE rb_cLibBPFRubyLink;
+
+static ID id_ivar_object;
+static ID id_ivar_program;
+static ID id_kwarg_retprobe;
+static ID id_kwarg_pid;
+static ID id_kwarg_offset;
+static ID id_kwarg_func_name;
+
 typedef struct {
   struct bpf_object *bpf_object;
 } libbpf_ruby_object_t;
 
+typedef struct {
+  struct bpf_program *bpf_program;
+} libbpf_ruby_program_t;
+
+typedef struct {
+  struct bpf_link *bpf_link;
+} libbpf_ruby_link_t;
+
 static void libbpf_ruby_object_free(void *ptr) {
   libbpf_ruby_object_t *libbpf_ruby_object = (libbpf_ruby_object_t *)ptr;
   if (libbpf_ruby_object->bpf_object) {
@@ -23,6 +41,26 @@ static size_t libbpf_ruby_object_memsize(const void *ptr) {
   return sizeof(libbpf_ruby_object_t);
 }
 
+static void libbpf_ruby_program_free(void *ptr) {
+  xfree(ptr);
+}
+
+static size_t libbpf_ruby_program_memsize(const void *ptr) {
+  return sizeof(libbpf_ruby_program_t);
+}
+
+static void libbpf_ruby_link_free(void *ptr) {
+  libbpf_ruby_link_t *libbpf_ruby_link = (libbpf_ruby_link_t *)ptr;
+  if (libbpf_ruby_link->bpf_link) {
+    bpf_link__destroy(libbpf_ruby_link->bpf_link);
+  }
+  xfree(libbpf_ruby_link);
+}
+
+static size_t libbpf_ruby_link_memsize(const void *ptr) {
+  return sizeof(libbpf_ruby_link_t);
+}
+
 static const rb_data_type_t libbpf_ruby_object_type = {
   .wrap_struct_name = "LibBPFRuby::Object",
   .function = {
@@ -34,6 +72,184 @@ static const rb_data_type_t libbpf_ruby_object_type = {
   .flags = RUBY_TYPED_FREE_IMMEDIATELY
 };
 
+static const rb_data_type_t libbpf_ruby_program_type = {
+  .wrap_struct_name = "LibBPFRuby::Program",
+  .function = {
+    .dmark = NULL,
+    .dfree = libbpf_ruby_program_free,
+    .dsize = libbpf_ruby_program_memsize,
+    .dcompact = NULL
+  },
+  .flags = RUBY_TYPED_FREE_IMMEDIATELY
+};
+
+static const rb_data_type_t libbpf_ruby_link_type = {
+  .wrap_struct_name = "LibBPFRuby::Link",
+  .function = {
+    .dmark = NULL,
+    .dfree = libbpf_ruby_link_free,
+    .dsize = libbpf_ruby_link_memsize,
+    .dcompact = NULL
+  },
+  .flags = RUBY_TYPED_FREE_IMMEDIATELY
+};
+
+static VALUE libbpf_ruby_program_wrap(VALUE object, struct bpf_program *program) {
+  libbpf_ruby_program_t *libbpf_ruby_program;
+  VALUE obj = TypedData_Make_Struct(rb_cLibBPFRubyProgram, libbpf_ruby_program_t, &libbpf_ruby_program_type, libbpf_ruby_program);
+  libbpf_ruby_program->bpf_program = program;
+  rb_ivar_set(obj, id_ivar_object, object);
+  return obj;
+}
+
+static VALUE libbpf_ruby_link_wrap(VALUE program, struct bpf_link *link) {
+  libbpf_ruby_link_t *libbpf_ruby_link;
+  VALUE obj = TypedData_Make_Struct(rb_cLibBPFRubyLink, libbpf_ruby_link_t, &libbpf_ruby_link_type, libbpf_ruby_link);
+  libbpf_ruby_link->bpf_link = link;
+  rb_ivar_set(obj, id_ivar_program, program);
+  return obj;
+}
+
+static struct bpf_program *libbpf_ruby_program_bpf(VALUE self) {
+  libbpf_ruby_program_t *libbpf_ruby_program;
+  TypedData_Get_Struct(self, libbpf_ruby_program_t, &libbpf_ruby_program_type, libbpf_ruby_program);
+
+  libbpf_ruby_object_t *libbpf_ruby_object;
+  TypedData_Get_Struct(rb_ivar_get(self, id_ivar_object), libbpf_ruby_object_t, &libbpf_ruby_object_type, libbpf_ruby_object);
+  if (!libbpf_ruby_object->bpf_object) {
+    rb_raise(rb_eRuntimeError, "program's object is closed");
+  }
+  return libbpf_ruby_program->bpf_program;
+}
+
+typedef struct {
+  const char *path;
+  struct bpf_object *bpf_object;
+} nogvl_open_ctx_t;
+
+typedef struct {
+  struct bpf_object *bpf_object;
+  int err;
+} nogvl_load_ctx_t;
+
+typedef struct {
+  struct bpf_program *bpf_program;
+  struct bpf_link *bpf_link;
+} nogvl_attach_ctx_t;
+
+typedef struct {
+  struct bpf_program *bpf_program;
+  int int_arg;
+  struct bpf_link *bpf_link;
+} nogvl_attach_int_ctx_t;
+
+typedef struct {
+  struct bpf_program *bpf_program;
+  bool retprobe;
+  const char *func_name;
+  struct bpf_link *bpf_link;
+} nogvl_attach_kprobe_ctx_t;
+
+typedef struct {
+  struct bpf_program *bpf_program;
+  pid_t pid;
+  const char *binary_path;
+  size_t offset;
+  const struct bpf_uprobe_opts *opts;
+  struct bpf_link *bpf_link;
+} nogvl_attach_uprobe_ctx_t;
+
+typedef struct {
+  struct bpf_program *bpf_program;
+  const char *category;
+  const char *name;
+  struct bpf_link *bpf_link;
+} nogvl_attach_tracepoint_ctx_t;
+
+typedef struct {
+  struct bpf_program *bpf_program;
+  const char *name;
+  struct bpf_link *bpf_link;
+} nogvl_attach_raw_tracepoint_ctx_t;
+
+static void *nogvl_bpf_object__open_file(void *data) {
+  nogvl_open_ctx_t *ctx = data;
+  ctx->bpf_object = bpf_object__open_file(ctx->path, NULL);
+  return NULL;
+}
+
+static void *nogvl_bpf_object__load(void *data) {
+  nogvl_load_ctx_t *ctx = data;
+  ctx->err = bpf_object__load(ctx->bpf_object);
+  return NULL;
+}
+
+static void *nogvl_bpf_object__close(void *data) {
+  bpf_object__close(data);
+  return NULL;
+}
+
+static void *nogvl_bpf_link__destroy(void *data) {
+  bpf_link__destroy(data);
+  return NULL;
+}
+
+static void *nogvl_bpf_program__attach(void *data) {
+  nogvl_attach_ctx_t *ctx = data;
+  ctx->bpf_link = bpf_program__attach(ctx->bpf_program);
+  return NULL;
+}
+
+static void *nogvl_bpf_program__attach_xdp(void *data) {
+  nogvl_attach_int_ctx_t *ctx = data;
+  ctx->bpf_link = bpf_program__attach_xdp(ctx->bpf_program, ctx->int_arg);
+  return NULL;
+}
+
+#ifdef HAVE_BPF_PROGRAM__ATTACH_TCX
+static void *nogvl_bpf_program__attach_tcx(void *data) {
+  nogvl_attach_int_ctx_t *ctx = data;
+  ctx->bpf_link = bpf_program__attach_tcx(ctx->bpf_program, ctx->int_arg, NULL);
+  return NULL;
+}
+#endif
+
+static void *nogvl_bpf_program__attach_kprobe(void *data) {
+  nogvl_attach_kprobe_ctx_t *ctx = data;
+  ctx->bpf_link = bpf_program__attach_kprobe(ctx->bpf_program, ctx->retprobe, ctx->func_name);
+  return NULL;
+}
+
+static void *nogvl_bpf_program__attach_uprobe_opts(void *data) {
+  nogvl_attach_uprobe_ctx_t *ctx = data;
+  ctx->bpf_link = bpf_program__attach_uprobe_opts(ctx->bpf_program, ctx->pid, ctx->binary_path, ctx->offset, ctx->opts);
+  return NULL;
+}
+
+static void *nogvl_bpf_program__attach_tracepoint(void *data) {
+  nogvl_attach_tracepoint_ctx_t *ctx = data;
+  ctx->bpf_link = bpf_program__attach_tracepoint(ctx->bpf_program, ctx->category, ctx->name);
+  return NULL;
+}
+
+static void *nogvl_bpf_program__attach_raw_tracepoint(void *data) {
+  nogvl_attach_raw_tracepoint_ctx_t *ctx = data;
+  ctx->bpf_link = bpf_program__attach_raw_tracepoint(ctx->bpf_program, ctx->name);
+  return NULL;
+}
+
+static void *nogvl_bpf_program__attach_cgroup(void *data) {
+  nogvl_attach_int_ctx_t *ctx = data;
+  ctx->bpf_link = bpf_program__attach_cgroup(ctx->bpf_program, ctx->int_arg);
+  return NULL;
+}
+
+static void *nogvl_bpf_program__attach_perf_event(void *data) {
+  nogvl_attach_int_ctx_t *ctx = data;
+  ctx->bpf_link = bpf_program__attach_perf_event(ctx->bpf_program, ctx->int_arg);
+  return NULL;
+}
+
 static VALUE rb_cObject_allocate(VALUE klass) {
   libbpf_ruby_object_t *libbpf_ruby_object;
   VALUE obj = TypedData_Make_Struct(klass, libbpf_ruby_object_t, &libbpf_ruby_object_type, libbpf_ruby_object);
@@ -44,22 +260,38 @@ static VALUE rb_cObject_allocate(VALUE klass) {
 static VALUE rb_cObject_initialize(VALUE self, VALUE path) {
   libbpf_ruby_object_t *libbpf_ruby_object;
   TypedData_Get_Struct(self, libbpf_ruby_object_t, &libbpf_ruby_object_type, libbpf_ruby_object);
-  const char *path_str = StringValueCStr(path);
+  StringValueCStr(path);
+  VALUE frozen_path = rb_str_new_frozen(path);
 
-  struct bpf_object *bpf_object = bpf_object__open_file(path_str, NULL);
-  long err = libbpf_get_error(bpf_object);
+  nogvl_open_ctx_t open_ctx = { .path = RSTRING_PTR(frozen_path) };
+  rb_nogvl(nogvl_bpf_object__open_file, &open_ctx, NULL, NULL, 0);
+  long err = libbpf_get_error(open_ctx.bpf_object);
   if (err) {
     rb_raise(rb_eRuntimeError, "bpf_object__open_file failed: %s", strerror(-err));
   }
-  err = bpf_object__load(bpf_object);
-  if (err) {
-    bpf_object__close(bpf_object);
-    rb_raise(rb_eRuntimeError, "bpf_object__load failed: %s", strerror(-err));
+
+  nogvl_load_ctx_t load_ctx = { .bpf_object = open_ctx.bpf_object };
+  rb_nogvl(nogvl_bpf_object__load, &load_ctx, NULL, NULL, 0);
+  if (load_ctx.err) {
+    rb_nogvl(nogvl_bpf_object__close, open_ctx.bpf_object, NULL, NULL, 0);
+    rb_raise(rb_eRuntimeError, "bpf_object__load failed: %s", strerror(-load_ctx.err));
   }
-  libbpf_ruby_object->bpf_object = bpf_object;
+  libbpf_ruby_object->bpf_object = open_ctx.bpf_object;
   return self;
 }
 
+static VALUE rb_cObject_program(VALUE self, VALUE name) {
+  libbpf_ruby_object_t *libbpf_ruby_object;
+  TypedData_Get_Struct(self, libbpf_ruby_object_t, &libbpf_ruby_object_type, libbpf_ruby_object);
+  const char *name_str = StringValueCStr(name);
+
+  struct bpf_program *program = bpf_object__find_program_by_name(libbpf_ruby_object->bpf_object, name_str);
+  if (!program) {
+    rb_raise(rb_eRuntimeError, "program %s not found", name_str);
+  }
+  return libbpf_ruby_program_wrap(self, program);
+}
+
 static VALUE rb_cObject_program_fd(VALUE self, VALUE name) {
   libbpf_ruby_object_t *libbpf_ruby_object;
   TypedData_Get_Struct(self, libbpf_ruby_object_t, &libbpf_ruby_object_type, libbpf_ruby_object);
@@ -88,12 +320,199 @@ static VALUE rb_cObject_close(VALUE self) {
   libbpf_ruby_object_t *libbpf_ruby_object;
   TypedData_Get_Struct(self, libbpf_ruby_object_t, &libbpf_ruby_object_type, libbpf_ruby_object);
   if (libbpf_ruby_object->bpf_object) {
-    bpf_object__close(libbpf_ruby_object->bpf_object);
+    rb_nogvl(nogvl_bpf_object__close, libbpf_ruby_object->bpf_object, NULL, NULL, 0);
     libbpf_ruby_object->bpf_object = NULL;
   }
   return Qnil;
 }
 
+static VALUE rb_cProgram_fd(VALUE self) {
+  return INT2NUM(bpf_program__fd(libbpf_ruby_program_bpf(self)));
+}
+
+static VALUE rb_cProgram_name(VALUE self) {
+  return rb_str_new_cstr(bpf_program__name(libbpf_ruby_program_bpf(self)));
+}
+
+static VALUE rb_cProgram_attach(VALUE self) {
+  nogvl_attach_ctx_t ctx = { .bpf_program = libbpf_ruby_program_bpf(self) };
+  rb_nogvl(nogvl_bpf_program__attach, &ctx, NULL, NULL, 0);
+  long err = libbpf_get_error(ctx.bpf_link);
+  if (err) {
+    rb_raise(rb_eRuntimeError, "bpf_program__attach failed: %s", strerror(-err));
+  }
+  return libbpf_ruby_link_wrap(self, ctx.bpf_link);
+}
+
+static VALUE rb_cProgram_attach_xdp(VALUE self, VALUE ifindex) {
+  nogvl_attach_int_ctx_t ctx = { .bpf_program = libbpf_ruby_program_bpf(self), .int_arg = NUM2INT(ifindex) };
+  rb_nogvl(nogvl_bpf_program__attach_xdp, &ctx, NULL, NULL, 0);
+  long err = libbpf_get_error(ctx.bpf_link);
+  if (err) {
+    rb_raise(rb_eRuntimeError, "bpf_program__attach_xdp failed: %s", strerror(-err));
+  }
+  return libbpf_ruby_link_wrap(self, ctx.bpf_link);
+}
+
+#ifdef HAVE_BPF_PROGRAM__ATTACH_TCX
+static VALUE rb_cProgram_attach_tcx(VALUE self, VALUE ifindex) {
+  nogvl_attach_int_ctx_t ctx = { .bpf_program = libbpf_ruby_program_bpf(self), .int_arg = NUM2INT(ifindex) };
+  rb_nogvl(nogvl_bpf_program__attach_tcx, &ctx, NULL, NULL, 0);
+  long err = libbpf_get_error(ctx.bpf_link);
+  if (err) {
+    rb_raise(rb_eRuntimeError, "bpf_program__attach_tcx failed: %s", strerror(-err));
+  }
+  return libbpf_ruby_link_wrap(self, ctx.bpf_link);
+}
+#endif
+
+static VALUE rb_cProgram_attach_kprobe(int argc, VALUE *argv, VALUE self) {
+  VALUE func_name, kwargs;
+  rb_scan_args(argc, argv, "1:", &func_name, &kwargs);
+  bool retprobe = false;
+  if (!NIL_P(kwargs)) {
+    VALUE value = rb_hash_lookup2(kwargs, ID2SYM(id_kwarg_retprobe), Qundef);
+    if (value != Qundef) retprobe = RTEST(value);
+  }
+  StringValueCStr(func_name);
+  VALUE frozen_func_name = rb_str_new_frozen(func_name);
+
+  nogvl_attach_kprobe_ctx_t ctx = {
+    .bpf_program = libbpf_ruby_program_bpf(self),
+    .retprobe = retprobe,
+    .func_name = RSTRING_PTR(frozen_func_name)
+  };
+  rb_nogvl(nogvl_bpf_program__attach_kprobe, &ctx, NULL, NULL, 0);
+  long err = libbpf_get_error(ctx.bpf_link);
+  if (err) {
+    rb_raise(rb_eRuntimeError, "bpf_program__attach_kprobe failed: %s", strerror(-err));
+  }
+  return libbpf_ruby_link_wrap(self, ctx.bpf_link);
+}
+
+static VALUE rb_cProgram_attach_uprobe(int argc, VALUE *argv, VALUE self) {
+  VALUE binary_path, kwargs;
+  rb_scan_args(argc, argv, "1:", &binary_path, &kwargs);
+  VALUE frozen_func_name = Qnil;
+  size_t offset = 0;
+  pid_t pid = -1;
+  bool retprobe = false;
+  if (!NIL_P(kwargs)) {
+    VALUE value;
+    value = rb_hash_lookup2(kwargs, ID2SYM(id_kwarg_func_name), Qundef);
+    if (value != Qundef) {
+      StringValueCStr(value);
+      frozen_func_name = rb_str_new_frozen(value);
+    }
+    value = rb_hash_lookup2(kwargs, ID2SYM(id_kwarg_offset), Qundef);
+    if (value != Qundef) offset = NUM2SIZET(value);
+    value = rb_hash_lookup2(kwargs, ID2SYM(id_kwarg_pid), Qundef);
+    if (value != Qundef) pid = NUM2INT(value);
+    value = rb_hash_lookup2(kwargs, ID2SYM(id_kwarg_retprobe), Qundef);
+    if (value != Qundef) retprobe = RTEST(value);
+  }
+  StringValueCStr(binary_path);
+  VALUE frozen_binary_path = rb_str_new_frozen(binary_path);
+
+  LIBBPF_OPTS(bpf_uprobe_opts, uopts,
+    .retprobe = retprobe,
+    .func_name = NIL_P(frozen_func_name) ? NULL : RSTRING_PTR(frozen_func_name)
+  );
+  nogvl_attach_uprobe_ctx_t ctx = {
+    .bpf_program = libbpf_ruby_program_bpf(self),
+    .pid = pid,
+    .binary_path = RSTRING_PTR(frozen_binary_path),
+    .offset = offset,
+    .opts = &uopts
+  };
+  rb_nogvl(nogvl_bpf_program__attach_uprobe_opts, &ctx, NULL, NULL, 0);
+  long err = libbpf_get_error(ctx.bpf_link);
+  if (err) {
+    rb_raise(rb_eRuntimeError, "bpf_program__attach_uprobe_opts failed: %s", strerror(-err));
+  }
+  return libbpf_ruby_link_wrap(self, ctx.bpf_link);
+}
+
+static VALUE rb_cProgram_attach_tracepoint(VALUE self, VALUE category, VALUE name) {
+  StringValueCStr(category);
+  StringValueCStr(name);
+  VALUE frozen_category = rb_str_new_frozen(category);
+  VALUE frozen_name = rb_str_new_frozen(name);
+
+  nogvl_attach_tracepoint_ctx_t ctx = {
+    .bpf_program = libbpf_ruby_program_bpf(self),
+    .category = RSTRING_PTR(frozen_category),
+    .name = RSTRING_PTR(frozen_name)
+  };
+  rb_nogvl(nogvl_bpf_program__attach_tracepoint, &ctx, NULL, NULL, 0);
+  long err = libbpf_get_error(ctx.bpf_link);
+  if (err) {
+    rb_raise(rb_eRuntimeError, "bpf_program__attach_tracepoint failed: %s", strerror(-err));
+  }
+  return libbpf_ruby_link_wrap(self, ctx.bpf_link);
+}
+
+static VALUE rb_cProgram_attach_raw_tracepoint(VALUE self, VALUE name) {
+  StringValueCStr(name);
+  VALUE frozen_name = rb_str_new_frozen(name);
+
+  nogvl_attach_raw_tracepoint_ctx_t ctx = {
+    .bpf_program = libbpf_ruby_program_bpf(self),
+    .name = RSTRING_PTR(frozen_name)
+  };
+  rb_nogvl(nogvl_bpf_program__attach_raw_tracepoint, &ctx, NULL, NULL, 0);
+  long err = libbpf_get_error(ctx.bpf_link);
+  if (err) {
+    rb_raise(rb_eRuntimeError, "bpf_program__attach_raw_tracepoint failed: %s", strerror(-err));
+  }
+  return libbpf_ruby_link_wrap(self, ctx.bpf_link);
+}
+
+static VALUE rb_cProgram_attach_cgroup(VALUE self, VALUE cgroup) {
+  nogvl_attach_int_ctx_t ctx = { .bpf_program = libbpf_ruby_program_bpf(self), .int_arg = rb_io_descriptor(cgroup) };
+  rb_nogvl(nogvl_bpf_program__attach_cgroup, &ctx, NULL, NULL, 0);
+  long err = libbpf_get_error(ctx.bpf_link);
+  if (err) {
+    rb_raise(rb_eRuntimeError, "bpf_program__attach_cgroup failed: %s", strerror(-err));
+  }
+  return libbpf_ruby_link_wrap(self, ctx.bpf_link);
+}
+
+static VALUE rb_cProgram_attach_perf_event(VALUE self, VALUE perf_event) {
+  struct bpf_program *program = libbpf_ruby_program_bpf(self);
+  int perf_fd = dup(rb_io_descriptor(perf_event));
+  if (perf_fd < 0) {
+    rb_raise(rb_eRuntimeError, "dup failed: %s", strerror(errno));
+  }
+  nogvl_attach_int_ctx_t ctx = { .bpf_program = program, .int_arg = perf_fd };
+  rb_nogvl(nogvl_bpf_program__attach_perf_event, &ctx, NULL, NULL, 0);
+  long err = libbpf_get_error(ctx.bpf_link);
+  if (err) {
+    close(perf_fd);
+    rb_raise(rb_eRuntimeError, "bpf_program__attach_perf_event failed: %s", strerror(-err));
+  }
+  return libbpf_ruby_link_wrap(self, ctx.bpf_link);
+}
+
+static VALUE rb_cLink_fd(VALUE self) {
+  libbpf_ruby_link_t *libbpf_ruby_link;
+  TypedData_Get_Struct(self, libbpf_ruby_link_t, &libbpf_ruby_link_type, libbpf_ruby_link);
+  if (!libbpf_ruby_link->bpf_link) {
+    rb_raise(rb_eRuntimeError, "link is detached");
+  }
+  return INT2NUM(bpf_link__fd(libbpf_ruby_link->bpf_link));
+}
+
+static VALUE rb_cLink_detach(VALUE self) {
+  libbpf_ruby_link_t *libbpf_ruby_link;
+  TypedData_Get_Struct(self, libbpf_ruby_link_t, &libbpf_ruby_link_type, libbpf_ruby_link);
+  if (libbpf_ruby_link->bpf_link) {
+    rb_nogvl(nogvl_bpf_link__destroy, libbpf_ruby_link->bpf_link, NULL, NULL, 0);
+    libbpf_ruby_link->bpf_link = NULL;
+  }
+  return Qnil;
+}
+
 static VALUE rb_mLibBPFRuby_map_update(VALUE self, VALUE map_fd, VALUE key, VALUE value) {
   Check_Type(key, T_STRING);
   Check_Type(value, T_STRING);
@@ -135,15 +554,44 @@ RUBY_FUNC_EXPORTED void Init_libbpf_ruby(void) {
   rb_ext_ractor_safe(true);
   libbpf_set_print(libbpf_ruby_print);
 
+  id_ivar_object = rb_intern("@object");
+  id_ivar_program = rb_intern("@program");
+  id_kwarg_retprobe = rb_intern("retprobe");
+  id_kwarg_pid = rb_intern("pid");
+  id_kwarg_offset = rb_intern("offset");
+  id_kwarg_func_name = rb_intern("func_name");
+
   VALUE rb_mLibBPFRuby = rb_define_module("LibBPFRuby");
   VALUE rb_cLibBPFRubyObject = rb_define_class_under(rb_mLibBPFRuby, "Object", rb_cObject);
+  rb_cLibBPFRubyProgram = rb_define_class_under(rb_mLibBPFRuby, "Program", rb_cObject);
+  rb_cLibBPFRubyLink = rb_define_class_under(rb_mLibBPFRuby, "Link", rb_cObject);
 
   rb_define_alloc_func(rb_cLibBPFRubyObject, rb_cObject_allocate);
   rb_define_method(rb_cLibBPFRubyObject, "initialize", rb_cObject_initialize, 1);
+  rb_define_method(rb_cLibBPFRubyObject, "program", rb_cObject_program, 1);
   rb_define_method(rb_cLibBPFRubyObject, "program_fd", rb_cObject_program_fd, 1);
   rb_define_method(rb_cLibBPFRubyObject, "map_fd", rb_cObject_map_fd, 1);
   rb_define_method(rb_cLibBPFRubyObject, "close", rb_cObject_close, 0);
 
+  rb_undef_alloc_func(rb_cLibBPFRubyProgram);
+  rb_define_method(rb_cLibBPFRubyProgram, "fd", rb_cProgram_fd, 0);
+  rb_define_method(rb_cLibBPFRubyProgram, "name", rb_cProgram_name, 0);
+  rb_define_method(rb_cLibBPFRubyProgram, "attach", rb_cProgram_attach, 0);
+  rb_define_method(rb_cLibBPFRubyProgram, "attach_xdp", rb_cProgram_attach_xdp, 1);
+#ifdef HAVE_BPF_PROGRAM__ATTACH_TCX
+  rb_define_method(rb_cLibBPFRubyProgram, "attach_tcx", rb_cProgram_attach_tcx, 1);
+#endif
+  rb_define_method(rb_cLibBPFRubyProgram, "attach_kprobe", rb_cProgram_attach_kprobe, -1);
+  rb_define_method(rb_cLibBPFRubyProgram, "attach_uprobe", rb_cProgram_attach_uprobe, -1);
+  rb_define_method(rb_cLibBPFRubyProgram, "attach_tracepoint", rb_cProgram_attach_tracepoint, 2);
+  rb_define_method(rb_cLibBPFRubyProgram, "attach_raw_tracepoint", rb_cProgram_attach_raw_tracepoint, 1);
+  rb_define_method(rb_cLibBPFRubyProgram, "attach_cgroup", rb_cProgram_attach_cgroup, 1);
+  rb_define_method(rb_cLibBPFRubyProgram, "attach_perf_event", rb_cProgram_attach_perf_event, 1);
+
+  rb_undef_alloc_func(rb_cLibBPFRubyLink);
+  rb_define_method(rb_cLibBPFRubyLink, "fd", rb_cLink_fd, 0);
+  rb_define_method(rb_cLibBPFRubyLink, "detach", rb_cLink_detach, 0);
+
   rb_define_module_function(rb_mLibBPFRuby, "map_update", rb_mLibBPFRuby_map_update, 3);
   rb_define_module_function(rb_mLibBPFRuby, "sockmap_update", rb_mLibBPFRuby_sockmap_update, 3);
   rb_define_module_function(rb_mLibBPFRuby, "map_lookup", rb_mLibBPFRuby_map_lookup, 3);

data/ext/libbpf_ruby/libbpf_ruby.h

@@ -3,6 +3,7 @@
 
 #include "ruby.h"
 #include "ruby/io.h"
+#include "ruby/thread.h"
 #include "ruby/ractor.h"
 
 #include <bpf/bpf.h>
@@ -12,6 +13,7 @@
 #include <stdarg.h>
 #include <string.h>
 #include <sys/socket.h>
+#include <unistd.h>
 
 #ifndef SO_ATTACH_REUSEPORT_EBPF
 #define SO_ATTACH_REUSEPORT_EBPF 52

data/lib/libbpf-ruby/version.rb

@@ -1,5 +1,6 @@
+# rbs_inline: enabled
 # frozen_string_literal: true
 
 module LibBPFRuby
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/lib/libbpf-ruby.rb

@@ -1,3 +1,4 @@
+# rbs_inline: enabled
 # frozen_string_literal: true
 
 require "libbpf_ruby/libbpf_ruby"

data/tmp/aarch64-linux/stage/CHANGELOG.md

@@ -1,5 +1,22 @@
 ## [Unreleased]
 
+## [0.2.0] - 2026-08-09
+
+- Release the GVL during blocking libbpf calls
+- Add `Program#attach_perf_event`
+- Add `Program#attach_cgroup`
+- Add `Program#attach_raw_tracepoint`
+- Add `Program#attach_tracepoint`
+- Add `Program#attach_uprobe`
+- Add `Program#attach_kprobe`
+- Add `Program#attach_tcx`
+- Add `Program#attach_xdp`
+- Add `Program` and `Link` classes with `Program#attach`
+
+## [0.1.1] - 2026-07-05
+
+- Skip native extension compilation on non-Linux platforms
+
 ## [0.1.0] - 2026-07-05
 
 - Initial release

data/tmp/aarch64-linux/stage/README.md

@@ -21,7 +21,7 @@ If bundler is not being used to manage dependencies, install the gem by executin
 gem install libbpf-ruby
 ```
 
-The native extension links against [`libbpf`](https://github.com/libbpf/libbpf), which is Linux-only. On unsupported platforms `gem install` aborts with a message about the missing prerequisite.
+The native extension links against [`libbpf`](https://github.com/libbpf/libbpf), which is Linux-only. On unsupported platforms the gem installs without compiling the extension; requiring it at runtime raises `LoadError`.
 
 ## Usage
 
@@ -33,13 +33,21 @@ require "socket"
 
 object = LibBPFRuby::Object.new("my_program.bpf.o")
 
-program_fd = object.program_fd("my_program")
+# Map updates and reuseport-based load balancing:
 map_fd = object.map_fd("my_map")
-
 LibBPFRuby.map_update(map_fd, [0].pack("L"), [42].pack("L"))
 
 listening_socket = TCPServer.new(3000)
-LibBPFRuby.attach_reuseport(listening_socket, program_fd)
+LibBPFRuby.attach_reuseport(listening_socket, object.program_fd("my_reuseport_program"))
+
+# First-class Programs and Links for every other hook:
+lo_ifindex = File.read("/sys/class/net/lo/ifindex").to_i
+xdp_link = object.program("my_xdp_program").attach_xdp(lo_ifindex)
+kprobe_link = object.program("my_kprobe_program").attach_kprobe("do_nanosleep")
+tp_link = object.program("my_tracepoint_program").attach_tracepoint("syscalls", "sys_enter_read")
+
+# Detach explicitly, or let GC destroy the link:
+xdp_link.detach
 ```
 
 ## Development

data/tmp/aarch64-linux/stage/tmp/aarch64-linux/stage/CHANGELOG.md

@@ -0,0 +1,22 @@
+## [Unreleased]
+
+## [0.2.0] - 2026-08-09
+
+- Release the GVL during blocking libbpf calls
+- Add `Program#attach_perf_event`
+- Add `Program#attach_cgroup`
+- Add `Program#attach_raw_tracepoint`
+- Add `Program#attach_tracepoint`
+- Add `Program#attach_uprobe`
+- Add `Program#attach_kprobe`
+- Add `Program#attach_tcx`
+- Add `Program#attach_xdp`
+- Add `Program` and `Link` classes with `Program#attach`
+
+## [0.1.1] - 2026-07-05
+
+- Skip native extension compilation on non-Linux platforms
+
+## [0.1.0] - 2026-07-05
+
+- Initial release

data/tmp/aarch64-linux/stage/tmp/aarch64-linux/stage/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"libbpf-ruby" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at [djry1999@gmail.com](mailto:djry1999@gmail.com).

data/tmp/aarch64-linux/stage/tmp/aarch64-linux/stage/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Joshua Young
+
+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.

data/tmp/aarch64-linux/stage/tmp/aarch64-linux/stage/README.md

@@ -0,0 +1,69 @@
+# LibBPFRuby
+
+![Version](https://img.shields.io/gem/v/libbpf-ruby)
+![Build](https://badge.buildkite.com/c7ce68e58e1f481f8b62f452756532c75983ec5aeafb151dd3.svg)
+
+[`libbpf`](https://github.com/libbpf/libbpf) wrapper for Ruby.
+
+**Docs:** https://joshuay03.github.io/libbpf-ruby
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add libbpf-ruby
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install libbpf-ruby
+```
+
+The native extension links against [`libbpf`](https://github.com/libbpf/libbpf), which is Linux-only. On unsupported platforms the gem installs without compiling the extension; requiring it at runtime raises `LoadError`.
+
+## Usage
+
+```ruby
+# frozen_string_literal: true
+
+require "libbpf-ruby"
+require "socket"
+
+object = LibBPFRuby::Object.new("my_program.bpf.o")
+
+# Map updates and reuseport-based load balancing:
+map_fd = object.map_fd("my_map")
+LibBPFRuby.map_update(map_fd, [0].pack("L"), [42].pack("L"))
+
+listening_socket = TCPServer.new(3000)
+LibBPFRuby.attach_reuseport(listening_socket, object.program_fd("my_reuseport_program"))
+
+# First-class Programs and Links for every other hook:
+lo_ifindex = File.read("/sys/class/net/lo/ifindex").to_i
+xdp_link = object.program("my_xdp_program").attach_xdp(lo_ifindex)
+kprobe_link = object.program("my_kprobe_program").attach_kprobe("do_nanosleep")
+tp_link = object.program("my_tracepoint_program").attach_tracepoint("syscalls", "sys_enter_read")
+
+# Detach explicitly, or let GC destroy the link:
+xdp_link.detach
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rake` to compile native extensions and run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+If you're on macOS (or any non-Linux host), `bin/dev` builds and drops you into a Docker image with `libbpf-dev`, `clang`, and Ruby preinstalled, mounting the repo at `/workspace`. Run `bin/dev` for an interactive shell, or `bin/dev bundle exec rake` to run the full build and test cycle in one shot.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/joshuay03/libbpf-ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/joshuay03/libbpf-ruby/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the LibBPFRuby project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/joshuay03/libbpf-ruby/blob/main/CODE_OF_CONDUCT.md).

data/tmp/aarch64-linux/stage/tmp/aarch64-linux/stage/libbpf-ruby.gemspec

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "lib/libbpf-ruby/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "libbpf-ruby"
+  spec.version = LibBPFRuby::VERSION
+  spec.authors = ["Joshua Young"]
+  spec.email = ["djry1999@gmail.com"]
+
+  spec.summary = "libbpf wrapper for Ruby"
+  spec.homepage = "https://github.com/joshuay03/libbpf-ruby"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.3.0"
+
+  spec.metadata["documentation_uri"] = "https://joshuay03.github.io/libbpf-ruby/"
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
+  spec.files = Dir["lib/**/*.rb", "ext/**/*.{rb,c,h}", "**/*.{gemspec,md,txt}"]
+  spec.require_paths = ["lib"]
+  spec.extensions = ["ext/libbpf_ruby/extconf.rb"]
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: libbpf-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Joshua Young
@@ -31,6 +31,11 @@ files:
 - tmp/aarch64-linux/stage/LICENSE.txt
 - tmp/aarch64-linux/stage/README.md
 - tmp/aarch64-linux/stage/libbpf-ruby.gemspec
+- tmp/aarch64-linux/stage/tmp/aarch64-linux/stage/CHANGELOG.md
+- tmp/aarch64-linux/stage/tmp/aarch64-linux/stage/CODE_OF_CONDUCT.md
+- tmp/aarch64-linux/stage/tmp/aarch64-linux/stage/LICENSE.txt
+- tmp/aarch64-linux/stage/tmp/aarch64-linux/stage/README.md
+- tmp/aarch64-linux/stage/tmp/aarch64-linux/stage/libbpf-ruby.gemspec
 homepage: https://github.com/joshuay03/libbpf-ruby
 licenses:
 - MIT
@@ -52,7 +57,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.16
 specification_version: 4
 summary: libbpf wrapper for Ruby
 test_files: []