C-GLib

Active contributors: Sten Larsson, Sutou Kouhei, Hiroyuki Sato

The c_glib/ directory provides GObject-based C wrappers around the C++ library. Once built, the libraries (libarrow-glib, libparquet-glib, libarrow-flight-glib, etc.) are usable from any GObject-Introspection-aware language: C, Vala, Python (via PyGObject), Lua, JavaScript (gjs), Crystal, and — most importantly for this repo — Ruby.

Purpose

Provide language-binding-friendly wrappers around the C++ library for languages that prefer GObject over a raw C++ FFI. The Ruby gems in ruby/ and many community-maintained Arrow bindings (Crystal, D, Lua, ...) use these wrappers.

Layout

c_glib/
├── meson.build, meson_options.txt   # Build system (Meson)
├── README.md, Brewfile, Gemfile, vcpkg.json
├── arrow-glib/             # Wraps libarrow
├── arrow-cuda-glib/        # CUDA-aware Arrow
├── arrow-dataset-glib/     # Wraps libarrow-dataset
├── arrow-flight-glib/      # Wraps libarrow-flight
├── arrow-flight-sql-glib/  # Wraps libarrow-flight-sql
├── parquet-glib/           # Wraps libparquet
├── gandiva-glib/           # Wraps libgandiva
├── doc/                    # GTK-Doc / DocBook reference manual
├── example/                # Standalone C examples
├── test/                   # Tests written in Ruby (run via test-unit)
└── tool/                   # Helper scripts

How it works

Each subdirectory builds an independent shared library. The pattern is:

• *-impl.{c,h} files implement GObject classes that hold a std::shared_ptr<Cpp::Type> in their private struct.
• *.{c,h} files implement public C wrappers that call into the C++ library through extern "C" shims.
• A meson.build per subdir compiles the C++ sources alongside the C wrapper sources.
• GObject introspection (g-ir-scanner) emits Arrow-1.0.gir / Arrow-1.0.typelib files so dynamic languages can discover the API.

The naming follows GLib conventions: types are GArrowArray, GArrowSchema, GParquetArrowFileReader, GArrowFlightServer. Methods are garrow_array_get_value_type, gparquet_arrow_file_reader_read_table. Errors flow through GError.

Examples

c_glib/example/ ships standalone programs:

• A simple "build an array and print it" demo.
• A Parquet read/write example.
• A Flight client/server pair.

These double as smoke tests and integration documentation.

Documentation

c_glib/doc/ configures GTK-Doc (the GLib documentation tooling) to produce a reference manual covering every public class. The output is suitable for devhelp. The Apache Arrow website doesn't host this directly; downstream packagers ship it as a -doc package.

Tests

c_glib/test/ is itself a Ruby test suite that exercises the GLib bindings via PyGObject-style introspection. The Rakefile (c_glib/test/run-test.rb invoked by c_glib/Gemfile/Rakefile) sets up the typelib path and runs test-unit against every type wrapper.

CI for c_glib lives in .github/workflows/cpp.yml (which co-builds c_glib in many of its matrix jobs) and the dedicated compose.yaml services like ubuntu-c-glib, fedora-c-glib.

Why GObject

GObject was chosen because:

• It has a stable, well-known C ABI suitable for FFI.
• Many existing dynamic-language ecosystems already understand GObject Introspection.
• Garbage-collected reference counting (g_object_ref/g_object_unref) maps cleanly to Arrow's std::shared_ptr semantics.
• Errors as GError** is a natural translation of arrow::Status.

Downstream

Red Arrow (the Ruby gems in ruby/) is the most actively maintained downstream consumer. Each Ruby gem mirrors a c_glib library:

c_glib library	Ruby gem
arrow-glib	red-arrow
arrow-cuda-glib	red-arrow-cuda
arrow-dataset-glib	red-arrow-dataset
arrow-flight-glib	red-arrow-flight
arrow-flight-sql-glib	red-arrow-flight-sql
parquet-glib	red-parquet
gandiva-glib	red-gandiva

See Ruby for the gem-level details.