Otegami Letter

Apache Arrow の Ruby バインディングに新機能を追加する実装編 Part4

2023-08-31T12:28:45+00:00

最初に

Red Data Tools開発者に聞け！Apache Arrow の Ruby バインディングに新機能を追加するシリーズの中で、kou さんが解説してくださった内容を簡単にまとめるシリーズになります。今回は Part14 で紹介された内容をまとめていきます。

動画で kou さんがサクッと解説してくださっています。動画で見たい方は上のリンクを参照してください！

記事の位置付け

追加したい機能を Ruby で実装してイメージを掴む
Ruby が提供する C の API を利用してどのように実装していくのか学ぶ
追加対象に関連するコードを読み解いていく
追加機能の実装を行う <- 今回の記事はここ

前回までのあらすじ

前回は、既存の Arrow::Table#raw_records の内部実装を読むことを通してコードベースの理解を深めるとともに実装イメージを掴みました。今回は、実際に Arrow::Table#raw_each_record の実装を行っていきましょう！一気に作業をすると大変なのでおおまかな作業の流れをまとめて少しずつ実装していきます。

おおまかな作業の流れ

下記の 4 つのステップで実装していこうと思います。

Ruby C API で Ruby のメソッドを定義する
Ruby C API で呼び出す C++ のメソッドを定義する
列指向のデータ構造を行指向のデータ構造に変換するための RawRecordsProducer クラスを定義する
変換結果を逐次的に yield して返す RawRecordsProducer#produce の実装する

1. Ruby C API で Ruby のメソッドを定義する

Arrow::Table#raw_records が定義されていたように Arrow::Table#each_raw_record を定義してあげたいので同様な形で書いてあげましょう！

// ruby/red-arrow/ext/arrow/arrow.cpp
auto cArrowTable = rb_const_get_at(mArrow, rb_intern("Table"));
rb_define_method(cArrowTable, "each_raw_record",
                 reinterpret_cast<>("TODO: C++ のメソッドを定義する必要あり")),
                 0);

Ruby C API の rb_define_method を利用して、Arrow::Table に each_raw_record を定義します。これで Ruby からは、Arrow::Table#each_raw_record が見えるようになります。ただ、Ruby の世界で呼ばれた時に実際に実行したい C++ レイヤーのメソッドが登録されていないので何もしないメソッドになってしまっているので、次に C++ レイヤーのメソッドを定義してあげます。

2. Ruby C API で呼び出す C++ のメソッドを定義する

Ruby C API から実際に呼び出す C++ のメソッド red_arrow::record_batch_each_raw_record を定義してあげます。まずはメソッドを定義したいだけなので Qnil を返すだけにしてあげます。

// ruby/red-arrow/ext/arrow/arrow.cpp
rb_define_method(cArrowTable, "each_raw_record",
                 reinterpret_cast<rb::RawMethod>(red_arrow::table_each_raw_record),
                 0);

// ruby/red-arrow/ext/arrow/raw-records.cpp
namespace red_arrow {
  namespace {
    VALUE
    table_each_raw_record(VALUE rb_table) {
      return Qnil;
    }
  }
}

実際にちゃんと呼ばれているのか少し試してみましょう！変更をコンパイルして反映してあげてから、コンパイルされたオブジェクトファイルを参照してあげるようにして irb 上で確認します。

% make -C ext/arrow/
% bundle exec env DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:/tmp/local/lib irb -I ext/arrow
irb(main):001:0> require 'arrow'
irb(main):002:0> Arrow::Table.new(number: [1, 2, 3]).each_raw_record
=> nil

無事に Arrow::Table#each_raw_record が実行されていそうですね。nil も返ってきていそうです。では、いよいよ行毎に yield して返すイテレーター部分の実装に入っていきましょう！

3. 列指向のデータ構造を行指向のデータ構造に変換するための RawRecordsProducer クラスを定義する

red_arrow::table_each_raw_record メソッドから red_arrow::table_raw_records メソッドのようにカラム指向のデータ構造を列指向のデータ構造に変換する責務をになった RawRecordsProducer Class クラスを呼び出すようにしてあげましょう。

なぜ、新しく RawRecordsProducer を定義するかというと前回見たように RawRecordsBuilder では全てのデータを変換してから値を返す実装になっており、今回実装したいイテレーターとは根本的な役割が異なるため新しく定義をしています。

// ruby/red-arrow/ext/arrow/raw-records.cpp
namespace red_arrow {
  namespace {
    class RawRecordsProducer : private Converter, public arrow::ArrayVisitor {
    public:
      explicit RawRecordsProducer()
        : Converter(),
          record_(Qnil), // 返却する行データを入れるの利用する
          column_index_(0),
          row_offset_(0) {
      }
    }

    VALUE
    table_each_raw_record(VALUE rb_table) {
      auto garrow_table = GARROW_TABLE(RVAL2GOBJ(rb_table));
      auto table = garrow_table_get_raw(garrow_table).get();

      try {
        RawRecordsProducer producer; // メインとなるのはココ
      } catch (rb::State& state) {
        state.jump();
      }

      return Qnil;
    }
  }
}

ここまでで、核となる「変換結果を逐次的に yield して返す」ロジック部分を実装するためのお膳立てができましたね。では最後のロジックの実装に移っていきます。

4. 変換結果を逐次的に yield して返す RawRecordsProducer#produce の実装する

今回の主体となる RawRecordsProducer クラスに対して変換し行毎に返すお仕事をしてもらうようのメソッド RawRecordsProducer#produce を定義していきます。

// ruby/red-arrow/ext/arrow/raw-records.cpp
namespace red_arrow {
  namespace {
    class RawRecordsProducer : private Converter, public arrow::ArrayVisitor {
    public:
      void produce(const arrow::Table& table) {
        rb::protect([&] {
          const auto n_columns = table.num_columns();
          const auto n_rows = table.num_rows();
          std::vector<int> chunk_indexes(n_columns);
          std::vector<int64_t> row_offsets(n_columns);
          for (int64_t i_row = 0; i_row < n_rows; ++i_row) {
            record_ = rb_ary_new_capa(n_columns);
            for (int i_column = 0; i_column < n_columns; ++i_column) {
              column_index_ = i_column;
              const auto chunked_array = table.column(i_column).get();
              auto& chunk_index = chunk_indexes[i_column];
              auto& row_offset = row_offsets[i_column];
              auto array = chunked_array->chunk(chunk_index).get();
              while (array->length() == row_offset) {
                ++chunk_index;
                row_offset = 0;
                array = chunked_array->chunk(chunk_index).get();
              }
              row_offset_ = row_offset;
              check_status(array->Accept(this),
                           "[table][each-raw-record]");
              ++row_offset;
            }
            rb_yield(record_);
          }

          return Qnil;
        });
      }
    }
  
    VALUE
    table_each_raw_record(VALUE rb_table) {
      auto garrow_table = GARROW_TABLE(RVAL2GOBJ(rb_table));
      auto table = garrow_table_get_raw(garrow_table).get();

      try {
        RawRecordsProducer producer;
        producer.produce(*table); 
      } catch (rb::State& state) {
        state.jump();
      }

      return Qnil;
    }
  }
}

一見 produce メソッドでやっていくことが複雑に見えますが、実は難しいことはしておらず大きく２つの仕事をしているだけです。(少し難しい部分としては、列のデータ量が多い場合は、 ChunkedArray という複数の要素から形成される場合も考慮する必要がある部分なのですが、今回はシンプルな解説にしたいので省いています。)

列指向のデータ構造から 1 行単位になるようにデータを抜き出して、record_ に格納してあげる
record_ に格納したデータを Ruby C API が提供する rb_yield に渡してあげて、1 行単位のデータを返してあげる

ここまでで、Arrow::Table#each_raw_record の実装は完了です。実際に動くか確認してみましょう。

変更をコンパイルして反映してあげてから、コンパイルされたオブジェクトファイルを参照してあげるようにして irb 上で確認します。ちゃんと行毎のデータがブロックに渡されて実行されていることがわかりました。問題なさそうですね。お疲れ様です！

% make -C ext/arrow/
% bundle exec env DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:/tmp/local/lib irb -I ext/arrow
irb(main):001:0> require 'arrow'
irb(main):002:0> Arrow::Table.new(number: [1, 2, 3]).each_raw_record { p _1 }
[1]
[2]
[3]
=> nil

最後に

「Apache Arrow の Ruby バインディングに新機能を追加する」を通して、「動的ライブラリとは」から「Rubyの仕組み」まで幅広い学びがありました。恥ずかしい話なのですが、普段は作成されたバインディングをライブラリ(gem)を通して利用するだけであったため何も知りませんでした。どこかの Rubyist が便利な機能を Ruby で使えるように道を用意してくれているから何も気にせずに私は利用できていたんだなと実感しました。

ただ、今回の体験を通して Ruby バインディングの作り方の基礎は理解できたのかなぁと思うので、これからは Rubyist が便利になる世界を作るのに貢献する側に回っていけたらと思っています！

最後に、全 15 回に及んでわかりやすく解説してくださった kou さんと一緒に開発に取り組んでくださった mterada1228 さんに改めてこの場でも感謝を伝えられたらと思います。本当にありがとうございました！！

Symbol not found in flat namespace - arrow.bundle(LoadError)

2023-08-08T23:37:19+00:00

最初に

Red Data Tools開発者に聞け！Apache Arrow の Ruby バインディングに新機能を追加するシリーズの中で、kou さんが解説してくださった内容を簡単にまとめるシリーズになります。今回は Part12 で紹介された内容をまとめていきます。

動画で kou さんがサクッと解説してくださっています。動画で見たい方は上のリンクを参照してください！

遭遇した問題

今回は、Red Arrow のテスト実行時に遭遇した下記のエラーになります。具体的には、対象のシンボルが見つからず LoadError になっている状態です。

% pwd
/dev/project/arrow/ruby/red-arrowdev/project/arrow/ruby/red-arrow
red-arrow % bundle exec env DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:/tmp/local/lib $(rbenv which ruby) test/run-test.rb
/dev/project/arrow/ruby/red-arrow/lib/arrow/loader.rb:146:in `require': dlopen(/dev/project/arrow/ruby/red-arrow/ext/arrow/arrow.bundle, 0x0009): symbol not found in flat namespace '__ZN9red_arrow21table_each_raw_recordEm' - /dev/project/arrow/ruby/red-arrow/ext/arrow/arrow.bundle (LoadError)
        from /dev/project/arrow/ruby/red-arrow/lib/arrow/loader.rb:146:in `require_extension_library'
        from /dev/project/arrow/ruby/red-arrow/lib/arrow/loader.rb:31:in `post_load'
        from /.rbenv/versions/3.2.0/lib/ruby/gems/3.2.0/gems/gobject-introspection-4.1.6/lib/gobject-introspection/loader.rb:49:in `block in load'
        from /.rbenv/versions/3.2.0/lib/ruby/gems/3.2.0/gems/gobject-introspection-4.1.6/lib/gobject-introspection/loader.rb:636:in `prepare_class'
        from /.rbenv/versions/3.2.0/lib/ruby/gems/3.2.0/gems/gobject-introspection-4.1.6/lib/gobject-introspection/loader.rb:41:in `load'
        from /.rbenv/versions/3.2.0/lib/ruby/gems/3.2.0/gems/gobject-introspection-4.1.6/lib/gobject-introspection/loader.rb:25:in `load'
        from /dev/project/arrow/ruby/red-arrow/lib/arrow/loader.rb:24:in `load'
        from /dev/project/arrow/ruby/red-arrow/lib/arrow.rb:29:in `<module:Arrow>'
        from /dev/project/arrow/ruby/red-arrow/lib/arrow.rb:25:in `<top (required)>'
        from /dev/project/arrow/ruby/red-arrow/test/helper.rb:18:in `require'
        from /dev/project/arrow/ruby/red-arrow/test/helper.rb:18:in `<top (required)>'
        from test/run-test.rb:67:in `require_relative'
        from test/run-test.rb:67:in `<main>'

対応策

エラーを見ると __ZN9red_arrow21table_each_raw_recordEm のようにマングリングされたシンボル情報が出ているので下記のコマンド(c++filt)でデマングルしてあげると、具体的に見つからないシンボル名を見ることができます。今回は、red_arrow::table_each_raw_record が見つかっていないようです。

% c++filt
__ZN9red_arrow21table_each_raw_recordEm
red_arrow::table_each_raw_record(unsigned long)

ソースコード内で red_arrow::table_each_raw_record に関する部分を探すと red_arrow::table_each_raw_records のようにタイポしているのを発見しました。タイポを修正し再度コンパイルを行った後に実行してあげると無事に実行できました。

% bundle exec env DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:/tmp/local/lib $(rbenv which ruby) -I ext/arrow sample.rb
[1, false]
[2, true]
[3, false]
[4, true]

ここからは、マングリングって何？と気になる人 or 上記で解決しない場合のもう少ししっかりしたデバッグ知識を得たい人向けになります。

マングリングとは？

C++はRubyと異なり、ネームスペース、クラス、関数のオーバーロードなどで同じ名前を持つ要素が存在します。コンパイルしてバイナリに変換する際、これらの名前はリンカーによって区別される必要があります。

ここで出てくるのが、「マングリング（Name Mangling）」です。マングリングは、コンパイラがバイナリレベルで名前を一意にするための自動変換を指します。この変換により、異なるネームスペース、クラス、オーバーロードされた関数も一意の名前を持つようになるのです。（バイナリ内の関数名などは「シンボル」として呼ばれます。）

マングリングを通じて、リンカーは関数や変数を正確に識別し、適切にリンクすることができるのです。

ref: https://www.ibm.com/docs/ja/i/7.5?topic=linkage-name-mangling-c-only

デマングルとは？

マングリングされたシンボルを元の名前に戻す変換になります。c++filt を利用することでデマングルを行うことができます。

ref: https://www.ibm.com/docs/ja/xl-c-and-cpp-aix/16.1?topic=utilities-demangling-compiled-c-names

対応策（詳細編）

デマングルすることで red_arrow::table_each_raw_record に問題があることがわかりました。では本当にこのシンボルがバイナリファイル(arrow.bundle)に存在しないのかを確認してみましょう！

バイナリファイル内からシンボルを探す

バイナリファイルは、人間には読みづらいので nm コマンドでファイル内のシンボル情報を表示してもらいましょう。

今回は、デマングルも同時に行いたいので -C オプションをつけてあげましょう。

下記のような結果が出てきましたので、それぞれが意味するところをみていきましょう！

% nm -C ext/arrow/arrow.bundle | grep red_arrow::table_each_raw_record
                 U red_arrow::table_each_raw_record(unsigned long)
00000000000077d8 T red_arrow::table_each_raw_records(unsigned long)

左からアドレス(シンボルのオフセット)シンボルのタイプ、シンボル名を表しています。では、U と T はそれぞれどういったシンボルのタイプなのかを確認してみましょう。 man コマンドで nm の説明を見ていきます。

% man nm

どうやら、U (undefined) は未定義状態、T (text section symbol)は、テキストシンボルであることがわかりました。つまり、red_arrow::table_each_raw_record は未定義状態であり、red_arrow::table_each_raw_records は定義されていることがわかります。なので、今回はタイポしていそうなことがわかります。

個人的に思ったこと

バイナリファイル(オブジェクトファイル)をデバックするなどと聞くと身構えてしまいますが、人間が理解しやすい形にツールを利用し変換してあげれば、簡単にデバックできることを学びました。デバックができればあとは Trial and error で学んでいけそうですね！

Apache Arrow の Ruby バインディングに新機能を追加する実装編 Part3

2023-07-26T11:23:15+00:00

最初に

Red Data Tools開発者に聞け！Apache Arrow の Ruby バインディングに新機能を追加するシリーズの中で、kou さんが解説してくださった内容を簡単にまとめるシリーズになります。今回は Part9 で紹介された内容をまとめていきます。

動画で kou さんがサクッと解説してくださっています。動画で見たい方は上のリンクを参照してください！

記事の位置付け

追加したい機能を Ruby で実装してイメージを掴む
Ruby が提供する C の API を利用してどのように実装していくのか学ぶ
追加対象に関連するコードを読み解いていく <- 今回の記事はここ
追加機能の実装を行う

前回までのあらすじ

前回は、Ruby の拡張ライブラリを実装する際の簡単なお作法や C API の利用方法を押さえていく中で、Ruby の C API を利用して大まかにどのような流れで実装していくのかを見ていきました。前回でおおまかな流れは抑えられたので、今回は実装に必要な知識を得るために内部実装を読んでいきましょう！

内部実装を読んでいくための入り口を決めよう

今回は Arrow::Table#raw_records イテラブルな結果を返すバージョンの Arrow::Table#raw_each_record を実装したいので、Arrow::Table#raw_records を読んでいきたいと思います！

すでに「Part1」で確認済みですが、実際にどのような結果が返ってくるのかを念の為おさらいをしていきます。 Arrow::Table で表現されるような表形式のデータを Arrow::Table#raw_records を利用することで行形式のデータに変換した値が返ってきます。メソッドの動作についての理解が深まったと思うので、次はその実装を詳しく見ていきましょう！

require 'arrow'

table = Arrow::Table.new(number: [1, 2, 3], string: ['a', 'b', 'c'])
p table
#<Arrow::Table:0x1050f2c00 ptr=0x106cfcbb0>
        number  string
0            1  a     
1            2  b     
2            3  c 

p table.raw_records
[[1, "a"], [2, "b"], [3, "c"]]

Arrow::Table#raw_records の実装を紐解いていく

Ruby の C API rb_define_method を利用して、raw_records は定義されています。メソッドの実態はどうやら red_arrow::table_raw_records で実装されていそうですね。

// ruby/red-arrow/ext/arrow/arrow.cpp
auto cArrowTable = rb_const_get_at(mArrow, rb_intern("Table"));
rb_define_method(cArrowTable, "raw_records",
                 reinterpret_cast<rb::RawMethod>(red_arrow::table_raw_records),
                 0);

ref: https://github.com/apache/arrow/blob/main/ruby/red-arrow/ext/arrow/arrow.cpp#L86-L89

red_arrow::table_raw_records

red_arrow::table_raw_records の実装は下記のようになっています。今回は全てを読み解いていくのは大変なので主要な部分を Pick Up して読んでいきます。

// ruby/red-arrow/ext/arrow/raw-records.cpp
namespace red_arrow {
  VALUE
  table_raw_records(VALUE rb_table) {
    auto garrow_table = GARROW_TABLE(RVAL2GOBJ(rb_table));
    auto table = garrow_table_get_raw(garrow_table).get();
    const auto n_rows = table->num_rows();
    const auto n_columns = table->num_columns();
    auto records = rb_ary_new_capa(n_rows);

    try {
      RawRecordsBuilder builder(records, n_columns);
      builder.build(*table);
    } catch (rb::State& state) {
      state.jump();
    }

    return records;　
  }
}

ref: https://github.com/apache/arrow/blob/main/ruby/red-arrow/ext/arrow/raw-records.cpp#L167-L183

まず確認したいのがメソッドの戻り値の型です。これは VALUE 型になっています。実は C レベルで Ruby の値の型は全て VALUE 型で表現されます。なので、ここでは戻り値も引数も VALUE 型として表現されています。

VALUE
table_raw_records(VALUE rb_table) { }

次に確認したいのが下記の部分です。C++ では Ruby とは異なり配列の大きさを動的に変化させるにはコストがかかるので、決められるところでは事前に大きさを決めておくのが大切です。 n_rows の分だけ rb_ary_new_capa を利用して配列の大きさを確保しています。今回の例ですと [[1, "a"], [2, "b"], [3, "c"]] のような値が返るので 3 とかになりますね。

auto records = rb_ary_new_capa(n_rows);

最後にメソッドの中核となる部分ですね。 RawRecordsBuilder class のインスタンスを生成して build メソッドを呼んでいます。次はここで実際になにをやっているのかを見ていきます。

RawRecordsBuilder builder(records, n_columns);
builder.build(*table);

その前に最後は records を返していますね。メソッドの戻り値としての [[1, "a"], [2, "b"], [3, "c"]] を返している部分ですね。

return records;

RawRecordsBuilder#build

RawRecordsBuilder の実装は下記のようになっています。こちらも全てを読み解いていくのは大変なので主要な部分を Pick Up して読んでいきます。

// ruby/red-arrow/ext/arrow/raw-records.cpp
class RawRecordsBuilder : private Converter, public arrow::ArrayVisitor {
public:
  explicit RawRecordsBuilder(VALUE records, int n_columns)
    : Converter(),
      records_(records),
      n_columns_(n_columns),
      is_produce_mode_(false) {
  }

  void build(const arrow::Table& table) {
    rb::protect([&] {
      const auto n_rows = table.num_rows();
      for (int64_t i = 0; i < n_rows; ++i) {
        auto record = rb_ary_new_capa(n_columns_);
        rb_ary_push(records_, record);
      }
      for (int i = 0; i < n_columns_; ++i) {
        const auto& chunked_array = table.column(i).get();
        column_index_ = i;
        row_offset_ = 0;
        for (const auto array : chunked_array->chunks()) {
          check_status(array->Accept(this),
                       "[table][raw-records]");
          row_offset_ += array->length();
        }
      }
      return Qnil;
    });
  }
}

ref: https://github.com/apache/arrow/blob/main/ruby/red-arrow/ext/arrow/raw-records.cpp#L50-L68

こちらが、RawRecordsBuilder のコンストラクターになります。特に複雑なことはやっておらず、引数で受け取った records と n_columns を、それぞれ records_ と n_columns_ に格納しています。 C++ には Ruby と違いインスタンス変数の概念がないので変数名の最後に _ をつけるなどコーディングスタイルでの識別を行うことが多いようです。なので records_ と n_columns_ はインスタンス変数としてこれから扱っていきます。

explicit RawRecordsBuilder(VALUE records, int n_columns)
  : Converter(),
    records_(records),
    n_columns_(n_columns) {
}

次に、RawRecordsBuilder#build を見ていきます。 build メソッド内でも色々やっていそうですね。一つずつ見ていきます。

まず最初にやっているのは、行の数分だけ格納用の領域を確保するということをやっています。 record ローカル変数に rb_ary_new_capa を利用しカラムの数ぶんだけの領域を確保した配列を代入しています。その record を rb_ary_push を通して records_ に代入して行ってます。今回の例で言うと [[], [], []] のような構造が作られたイメージです。

void build(const arrow::Table& table) {
  rb::protect([&] {
    const auto n_rows = table.num_rows();
    for (int64_t i = 0; i < n_rows; ++i) {
      auto record = rb_ary_new_capa(n_columns_);
      rb_ary_push(records_, record);
    }
    // ...
  });
}

次は、先ほど作った構造に実際に値を代入をしていく部分になります。見ていく前にここから少し Arrow 形式のデータ構造を元にしたコードになっています。なので今回全てを説明しませんが、気になる方はこちらの動画を見てみてください。

table.column(i).get() では、表形式なデータ Arrow Table からカラム毎のデータを取得しています。今回の例で言うと、number: [1, 2, 3] や string: ['a', 'b', 'c'] に相当する部分になります。最初の loop では number のみの配列を処理し次の loop では string のみの配列を処理するみたいな形です。

for (int i = 0; i < n_columns_; ++i) {
  const auto& chunked_array = table.column(i).get();
  column_index_ = i;
  row_offset_ = 0;
  // ...
}

そして、渡された配列毎に check_status(array->Accept(this), "[table][raw-records]") の処理を呼んでいます。実際にどんなことをしているのか見ていきましょう。

具体的に渡される配列は、[1, 2, 3] みたいな構造が渡されるイメージです(厳密には違うのですが簡略化のため)

for (const auto array : chunked_array->chunks()) { // ここの構造は今回説明しませんが、カラム毎の配列が渡されるイメージでいてください
  check_status(array->Accept(this),
                "[table][raw-records]");
  row_offset_ += array->length();
}

今回の大事な部分が array->Accept(this) になります。ここでは Accept に渡された VISIT メソッドを呼ぶようになっています。では、RawRecordsBuilder で定義されている VISIT メソッドを実際に見てみましょう。下記で少しだけ詳しくみると下記のようになっていますが、今回は説明を一旦省略します。

// cpp/src/arrow/array/array_base.cc
Status Array::Accept(ArrayVisitor* visitor) const {
  return VisitArrayInline(*this, visitor);
}

// cpp/src/arrow/visit_array_inline.h
template <typename VISITOR, typename... ARGS>
inline Status VisitArrayInline(const Array& array, VISITOR* visitor, ARGS&&... args) {
  switch (array.type_id()) {
    ARROW_GENERATE_FOR_ALL_TYPES(ARRAY_VISIT_INLINE);
    default:
      break;
  }
  return Status::NotImplemented("Type not implemented");
}

// cpp/src/arrow/visit_array_inline.h
#define ARRAY_VISIT_INLINE(TYPE_CLASS)                                                  
  case TYPE_CLASS##Type::type_id:                                                       
    return visitor->Visit(                                                              
        internal::checked_cast<const typename TypeTraits<TYPE_CLASS##Type>::ArrayType&>(
            array),                                                                     
        std::forward<ARGS>(args)...);

RawRecordsBuilder::VISIT(この表記は正確ではないですmm)

ここでは、渡された配列の型ごとに適切な関数を呼ぶような形で作られています。いわゆる Visitor パターンというやつですね。（Visitor パターンの説明はここでされてます。）そして実際に visit されて実行されるのは、convert(array) 関数になります。実はこれが今回の最も重要な部分になります。みていきましょう！

// ruby/red-arrow/ext/arrow/raw-records.cpp
#define VISIT(TYPE)                                                     \
      arrow::Status Visit(const arrow::TYPE ## Array& array) override { \
        convert(array);                                                 \
        return arrow::Status::OK();                                     \
      }

ref: https://github.com/apache/arrow/blob/main/ruby/red-arrow/ext/arrow/raw-records.cpp#L71-L75

RawRecordsBuilder convert

convert メソッド内では大きく二つの分岐があります。渡された配列に null となる値があるか否かです。今回は、よりシンプルな null が存在しない場合の処理（ else の部分）を追っていきます。

// ruby/red-arrow/ext/arrow/raw-records.cpp
template <typename ArrayType>
void convert(const ArrayType& array) {
  const auto n = array.length();
  if (array.null_count() > 0) {
    for (int64_t i = 0, ii = row_offset_; i < n; ++i, ++ii) {
      auto value = Qnil;
      if (!array.IsNull(i)) {
        value = convert_value(array, i);
      }
      auto record = rb_ary_entry(records_, ii);
      rb_ary_store(record, column_index_, value);
    }
  } else {
    for (int64_t i = 0, ii = row_offset_; i < n; ++i, ++ii) {
      auto record = rb_ary_entry(records_, ii);
      rb_ary_store(record, column_index_, convert_value(array, i));
    }
  }
}

ref: https://github.com/apache/arrow/blob/main/ruby/red-arrow/ext/arrow/raw-records.cpp#L115-L133

渡された配列の長さの分だけ下記の処理を繰り返します。今回の例で言うと [1, 2, 3] が渡された場合 3 回ループを回すイメージですね。次にループ内の処理を見ていきます。

const auto n = array.length();
if (array.null_count() > 0) {
  // ...
} else {
  for (int64_t i = 0, ii = row_offset_; i < n; ++i, ++ii) {
    // ...
  }
}

まず最初に rb_ary_entry を利用して先ほど行の分だけ空の配列を入れた records_ から、指定した行の空配列を取得してきます。（Ruby で言う array[0] みたいなイメージですね。）取得した配列を record に格納します。次に、rb_ary_store を利用して column_index_ で指定した行に convert_value で変換した値を代入します。(Ruby で言う array[0] = 1 みたいなイメージですね。) そうすることで列単位で渡されたデータを行単位のデータに追加していくことができます。

auto record = rb_ary_entry(records_, ii);
rb_ary_store(record, column_index_, convert_value(array, i));

具体的な例としては下記のようなステップで列ごとに対象の行のデータに追加していく感じです。こうすることで、列データごとに処理をまわし結果として行データに変換できるようにしています。

1列目のデータ: number: [1, 2, 3]
全ての行のデータ: [[1], [2], [3]]
2列目のデータ: string: ['a', 'b', 'c']
全ての行のデータ: [[1, 'a'], [2, 'b'], [3, 'c']]

最終的には、変換が終わった records_ つまり records が結果として返るわけです。これが、Arrow::Table#raw_records の内部実装になります。ここからわかることは、行単位で結果を逐次的に返すためには、既存の列ごとに行っている処理を行ごとに実行する実装をしてあげると良さそうですね。次回は実際に手を動かして実装していきましょう！

Apache Arrow の Ruby バインディングに新機能を追加する実装編 Part2

2023-07-18T22:56:00+00:00

最初に

Red Data Tools開発者に聞け！第13回 Apache Arrow の Ruby バインディングに新機能を追加するシリーズの中で、kou さんが解説してくださった内容を簡単にまとめるシリーズになります。今回は Part7 で紹介された内容をまとめていきます。

動画で kou さんがサクッと解説してくださっています。動画で見たい方は上のリンクを参照してください！

記事の位置付け

追加したい機能を Ruby で実装してイメージを掴む
Ruby が提供する C の API を利用してどのように実装していくのか学ぶ <- 今回の記事はここ
追加対象に関連するコードを読み解いていく
追加機能の実装を行う

前回までのあらすじ

前回は、「追加したい機能を Ruby で実装してイメージを掴む」ためにイテレータを Ruby レベルではどのように実装するのかをみていきました。今回は、前回実装したコードをもとに Ruby が提供する C の API を利用してどのように実装していくのかを関連するコードを確認しながらみていきましょう。

require 'arrow'

class Arrow::Table
  def each_raw_record
    raw_records.each do |row|
      yield row
    end
  end
end

C レイヤーでの実装の流れを掴む

Ruby レベルのイテレータ実装では、大きく 3 つのことを行っていました。

拡張ライブラリを require して読み込む
```
require 'arrow'
```
メソッドを定義する
```
def each_raw_record
  #...
end
```

yield してイテレートする

raw_records.each do |row|
  yield row
end

では次に Ruby が提供する C の API を利用してどのように上記の 3 つを実現するのかを見ていきましょう！

拡張ライブラリを `require` して読み込む

Ruby は拡張ライブラリを require してロードする際に「Init_ライブラリ名」という関数を自動で実行するようになっています。

Ruby の公式ドキュメント「Rubyの拡張ライブラリの作り方」を参照

実際に、red-arrow ではどうなっているのか確認して見ると、Init_arrow 関数が定義されています。つまり、Ruby レベルで require arrow をすると、Init_arrow が実行されるという流れになります。

extern "C" void Init_arrow() {
  // ...
}

ref: https://github.com/apache/arrow/blob/main/ruby/red-arrow/ext/arrow/arrow.cpp#L68

では次に、C レイヤーで「メソッドを定義する」のはどのように行うのかをみていきます。

メソッドを定義する

Ruby の C API は、rb で始まる関数を提供しています。例えば、実際に Arrow の拡張機能のコードを見てみると下記のメソッドが利用されています

rb_const_get
rb_define_method
rb_const_get_at
rb_intern

今回注目したいのは、rb_define_method です。これは、C レベルで Ruby の関数を定義するために Ruby が用意した C API になります。実際に利用例を見てみると、Arrow::Table に raw_records メソッドを定義しているのがわかります。

auto cArrowTable = rb_const_get_at(mArrow, rb_intern("Table"));
rb_define_method(cArrowTable, "raw_records",
                 reinterpret_cast<rb::RawMethod>(red_arrow::table_raw_records),
                 0);

ref: Rubyt C API: rb_define_method

では次に、C レイヤーで「yield してイテレートする」のはどのように行うのかをみていきます。

yield してイテレートする

実は、Ruby が rb_define_method C API を提供したいたのと同様に yield に関しても、rb_yield という API を提供してくれています。なので、こちらを利用してあげれば yield して結果を逐次的に返すことができます。

ref: Rubyt C API: rb_yield

ここまでで大まかに C API を利用した実装の流れが追えたので、次の記事では実際に実装な知識を得るために内部実装を読み解いていきます。

Apache Arrow の Ruby バインディングに新機能を追加する実装編 Part1

2023-06-30T00:18:32+00:00

最初に

動画で kou さんがサクッと解説してくださっています。動画で見たい方は上のリンクを参照してください！

前回までのあらすじ

Apache Arrow の Ruby バインディングが手元で動作するようになったので、遂に Ruby バインディングに新機能を追加するフェーズまでやってきました！では、実際にどんな機能を追加したく、どのように進めていくのかを確認していきます。

どんな機能を追加したいの？

Arrow::Table#raw_recordsという、Arrow::Table オブジェクトから作成した表データを Ruby の配列形式に変換するメソッドがあります。今回は、この配列への変換をイテラブルにするArrow::Table#raw_each_recordという機能を追加したいです。

> require 'arrow'
> arrow = Arrow::Table.new(number: [1, 2, 3], string: ['a', 'b', 'c'])
=> 
#<Arrow::Table:0x10a9d8ba8 ptr=0x12da8bd80>                                     
        number  string                                                          
0            1  a                                                               
1            2  b                                                               
2            3  c

> arrow.raw_records
=> [[1, "a"], [2, "b"], [3, "c"]]

どんな時に嬉しいのか？

どんな時にイテラブルに処理すると嬉しいのかという疑問があると思います。今回の例のように、データ量が少ない場合にはあまり問題になりません。しかし、不断 Arrow が取り扱うデータは大量であり、全てを一度に配列に変換すると処理が終わるまでに時間が掛かるという課題が存在します。

具体例として、ニューヨーク市の1ヶ月分のタクシー利用データ（100万件以上のデータ）を考えてみましょう。全体のデータを分析する必要はなく、最初の1000件だけを確認したいとします。全データの変換を待つのは時間がかかりますが、イテラブルな変換を利用すれば、最初の1000件のデータだけを短時間で取り出すことが可能になります。

ref: Added New York city’s Taxi and Limousine Commission For Hire Vehicle trip support

つまり、この機能があると嬉しい時は、「大量のデータの中から一部だけを効率よく分析したい」時となります。

どのように進めていくのか

実際になぜ必要なのかを共有できたので、実際に開発していく方針を考えてみましょう！今回は、初めての Apache Arrow の Ruby バインディングへの機能追加なので下記の手順で行なっていきます。

追加したい機能を Ruby で実装してイメージを掴む <- 今回の記事はここ
Ruby が提供する C の API を利用してどのように実装していくのか学ぶ
追加対象に関連するコードを読み解いていく
追加機能の実装を行う

1. 追加したい機能を Ruby で実装してイメージを掴む

Arrow::Table#raw_recordsをイテラブルに実行するArrow::Table#raw_each_recordを Ruby で簡単に実装してみます。

# /arrow/ruby/red-arrow/sample-each.rb
require 'arrow'

class Arrow::Table
  def each_raw_record
    raw_records.each do |row|
      yield row
    end
  end
end

Arrow::Table.new(number: [1, 2, 3], string: ['a', 'b', 'c']).each_raw_record { |row| p row }

% bundle exec env DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:/tmp/local/lib ruby -I ext/arrow sample-each.rb
[1, "a"]
[2, "b"]
[3, "c"]

上記のように Ruby でイテレータを作成するのは yield を利用することで簡単に作成することができます。今実装した例を元に、Ruby バインディングに機能追加をしてあげたら良さそうです。

大雑把には下記のフローで機能追加を実現しようと考えています。

既存の Arrow::Table#raw_records を利用して、変換が終わり次第一つずつ yield してあげる形で、Arrow::Table#raw_each_record を実装する。
次に既存の Arrow::Table#raw_records は一度に全てを変換してしまうので、一つずつ変換する機能を追加する。

次の記事では、今回実装イメージがついたので、実際に機能を追加する部分のコードを理解をするところから始めます。

Incompatible Library Version Error

2023-06-14T12:54:00+00:00

最初に

Red Data Tools開発者に聞け！第12回 Apache Arrow の Ruby バインディングに新機能を追加するシリーズの中で、kou さんが解説してくださった内容を簡単にまとめるシリーズになります。今回は Part7 で紹介された内容をまとめていきます。

kou さんがサクッと解説してくださっている動画は、こちらになります。

遭遇した問題

今回は、テスト実行時に発生した incompatible library version エラーになります。

% bundle exec env DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:/tmp/local/lib $(rbenv which ruby) test/run-test.rb
/Users/otegami/dev/project/arrow/ruby/red-arrow/lib/arrow/loader.rb:146:in `require': incompatible library version - /Users/otegami/dev/project/arrow/ruby/red-arrow/ext/arrow/arrow.bundle (LoadError)

対応策

arrow.bundle をビルドした Ruby のバージョンでテストを実行することで解決できます。

% bundle exec env DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:/tmp/local/lib $(rbenv which ruby) test/run-test.rb

何が起きているのか？

実行している Ruby が arrow.bundle が使っているlibrubyに対し、「ABI」（アプリケーションバイナリインターフェース）の互換性がなくエラーとなっている。

ABI とは
- バイナリレベルでの相互作用を規定しているもの（バイナリレベルのインターフェイス）
libruby とは
- Rubyプログラミング言語のコア機能を提供するライブラリです
- 普段使っている ruby コマンドは、libruby を呼び出してスクリプトを実行しているだけである

互換性のある `libruby` は何なのか確認する

otoolコマンドを利用して、arrow.bundle と互換性のある libruby を調査します。

otool は、実行可能ファイルフォーマットである Mach-O（Mach Object）ファイル形式を調査するためのコマンドです。
Mach-O は、コンパイラが生成するオブジェクトファイル並びに実行ファイルのフォーマットみたいです。（理解できていないので後日調べる）
-L は引数に与えられたライブラリが利用する共有ライブラリの一覧を表示します

% otool -L ext/arrow/arrow.bundle
ext/arrow/arrow.bundle:
  /Users/otegami/.rbenv/versions/3.2.0/lib/libruby.3.2.dylib (compatibility version 3.2.0, current version 3.2.0)

上記の結果から、libruby.3.2.dylib に依存していることがわかります。では、現在利用している Ruby はどのパージョンの libruby に依存しているのか確認してみます。

% otool -L $(rbenv which ruby)
/Users/otegami/.rbenv/versions/3.0.3/bin/ruby:
  /Users/otegami/.rbenv/versions/3.0.3/lib/libruby.3.0.dylib (compatibility version 3.0.0, current version 3.0.3)

libruby.3.0.dylib に依存していることがわかります。libruby のバージョンは Ruby のバージョンと互換性があるので、今回は、libruby.3.2.dylib を利用する Ruby v3.2.0 で実行してあげるとよさそうです。

% rbenv global 3.2.0
% ruby -v
ruby 3.2.0 (2022-12-25 revision a528908271) [arm64-darwin20]
% bundle exec env DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:/tmp/local/lib ruby test/run-test.rb
Loaded suite test
Started
......................................
Finished in 1.123513 seconds.
-----------------------------------------------------------------------------------------------------------------------------------
1610 tests, 1610 assertions, 0 failures, 0 errors, 0 pendings, 0 omissions, 0 notifications
100% passed
-----------------------------------------------------------------------------------------------------------------------------------
1433.01 tests/s, 1433.01 assertions/s

無事にテストが通りました！今までは、incompatible library version エラーが発生した場合、手探りで Ruby のバージョンを変更して問題を解決していましたが、今後は、libruby のバージョンを確認し、適切なバージョンの Ruby を選択することで問題を回避できます。また、他のライブラリでも依存関係を調べながら解決できるでしょう！

DYLD Environment Variables

2023-06-13T11:15:00+00:00

最初に

Red Data Tools開発者に聞け！第11回 Apache Arrow の Ruby バインディングに新機能を追加するシリーズの中で、kou さんが解説してくださった内容を簡単にまとめるシリーズになります。今回は Part6 で紹介された内容をまとめていきます。

kou さんがサクッと解説してくださっている動画は、こちらになります。

遭遇した問題

今回は、Red Arrow のテスト実行時に遭遇した下記のエラーになります。

% pwd
/arrow/ruby/red-arrow
% bundle exec rake test
(null)-WARNING **: Failed to load shared library 'libarrow-glib.1300.dylib' referenced by the typelib: dlopen(libarrow-glib.1300.dylib, 0x0009): tried: 'libarrow-glib.1300.dylib' (no such file), '/usr/local/lib/libarrow-glib.1300.dylib' (no such file), '/usr/lib/libarrow-glib.1300.dylib' (no such file), '/Users/otegami/dev/project/arrow/ruby/red-arrow/libarrow-glib.1300.dylib' (no such file), '/usr/local/lib/libarrow-glib.1300.dylib' (no such file), '/usr/lib/libarrow-glib.1300.dylib' (no such file)

対応策

下記のように実行することで問題を解決できます。その理由については以下で詳しく説明します。

% bundle exec env DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:/tmp/local/lib $(rbenv which ruby) test/run-test.rb

何が起きているのか？

DYLD_LIBRARY_PATH を探索したが、共有ライブラリ（動的ライブラリ）のlibarrow-glib.1300.dylib が見つからず、エラーになっています。

DYLD_LIBRARY_PATH とは、MacOS が共有ライブラリのパスを管理する環境変数になります。

今回はlibarrow-glib.1300.dylibが存在するパスを指定する必要がありそうです。

DYLD_LIBRARY_PATH に `libarrow-glib.1300.dylib` のパスを指定する

% ls /tmp/local/lib | grep libarrow-glib.1300.dylib
libarrow-glib.1300.dylib

/tmp/local/lib 配下に libarrow-glib.1300.dylib は存在することがわかったので、環境変数を指定してテストを実行してみます。

% DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:/tmp/local/lib bundle exec rake test
(null)-WARNING **: Failed to load shared library 'libarrow-glib.1300.dylib' referenced by the typelib: dlopen(libarrow-glib.1300.dylib, 0x0009): tried: 'libarrow-glib.1300.dylib' (no such file), '/usr/local/lib/libarrow-glib.1300.dylib' (no such file), '/usr/lib/libarrow-glib.1300.dylib' (no such file), '/Users/otegami/dev/project/arrow/ruby/red-arrow/libarrow-glib.1300.dylib' (no such file), '/usr/local/lib/libarrow-glib.1300.dylib' (no such file), '/usr/lib/libarrow-glib.1300.dylib' (no such file)

DYLD_LIBRARY_PATH の探索パスに指定した /tmp/local/lib/ が含まれていなさそうです。どうやら環境変数での指定が効いていなさそうです。なぜなんでしょうか？

MacOS 上で `DYLD_LIBRARY_PATH` は特別な環境変数である

試しに、Ruby が DYLD_LIBRARY_PATH 環境変数を認識しているか確認してみましょう。

% DYLD_LIBRARY_PATH=/tmp/local/lib ruby -e 'pp ENV' | grep DYLD_LIBRARY_PATH
# 何も参照されず、存在しない

環境変数名を XDYLD_LIBRARY_PATH に変更してあげると認識します。どうやら環境変数 DYLD_LIBRARY_PATH が特別な動きをしているように見えます。

% XDYLD_LIBRARY_PATH=/tmp/local/lib ruby -e 'pp ENV' | grep XDYLD_LIBRARY_PATH
 "XDYLD_LIBRARY_PATH"=>"/tmp/local/lib",

実は、DYLD_LIBRARY_PATH はサブプロセスには継承されないという仕様が存在します。なぜなら、実行時にどのライブラリを読み込むかを指定できるため、仮に指定できてしまうと実行中のプログラムをインターセプトできてしまうような問題が起きてしまいます。下記の Doc を参考にすると MacOS 側で読み込める用に設定を変えることもできそうですが、セキュリティ的によろしくなさそうなので、今回は利用しません。

では、テストをどうやってメインプロセスで実行するかを考えるために、まず現状どのように実行されているのかをみていきましょう。

ruby command はサブプロセスで実行されている？

ruby command の実体を確認してみましょう。次に示すファイルがそれに相当すると思われます。

type command は、which commnad よりも幅広い情報を提供します。（エイリアスが使われている場合は、その内容を報告してくれるなど）
```
% type ruby
ruby is /Users/otegami/.rbenv/shims/ruby
```

次にファイルの中身がなんなのかを file command で確認してみます。どうやら Shell Script で書かれているようです。

% file =ruby
/Users/otegami/.rbenv/shims/ruby: Bourne-Again shell script text executable, ASCII text

ファイルの中身は下記のようになっています。どうやらこれは rbenv をラップして実行する Shell Script のようです。これでは、サブプロセスになってしまうので、直接実行してあげるようにしてあげる必要がありそうです。

% cat =ruby
#!/usr/bin/env bash
set -e
[ -n "$RBENV_DEBUG" ] && set -x

program="${0##*/}"
if [ "$program" = "ruby" ]; then
  for arg; do
    case "$arg" in
    -e* | -- ) break ;;
    */* )
      if [ -f "$arg" ]; then
        export RBENV_DIR="${arg%/*}"
        break
      fi
      ;;
    esac
  done
fi

export RBENV_ROOT="/Users/otegami/.rbenv"
exec "/opt/homebrew/bin/rbenv" exec "$program" "$@"

直接実行するために rbenv which ruby の実体を確認してみると、バイナリのようです。つまり、この実行可能なバイナリを直接実行すれば、シェルによって実行されるので環境変数をそのまま渡せそうです。

% file =$(rbenv which ruby)
/Users/otegami/.rbenv/versions/3.2.0/bin/ruby: Mach-O 64-bit executable arm64

無事に DYLD_LIBRARY_PATH が参照でき、テストが通りました！

% bundle exec env DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:/tmp/local/lib $(rbenv which ruby) test/run-test.rb
......................................
Finished in 1.032504 seconds.
-----------------------------------------------------------------------------------------------------------------------------------
1610 tests, 1610 assertions, 0 failures, 0 errors, 0 pendings, 0 omissions, 0 notifications
100% passed
-----------------------------------------------------------------------------------------------------------------------------------
1559.32 tests/s, 1559.32 assertions/s

念の為、環境変数 DYLD_LIBRARY_PATH に指定した値を確認してみると、無事に参照できていそうです！

% bundle exec env DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:/tmp/local/lib $(rbenv which ruby) -e 'pp ENV' | grep DY
"DYLD_LIBRARY_PATH"=>":/tmp/local/lib",

Static link と Dynamic Link

2023-06-06T13:17:25+00:00

最初に

Red Data Tools開発者に聞け！第6回　Apache ArrowのRubyバインディングに新機能を追加するシリーズの中で、kou さんが解説してくださった内容を簡単にまとめるシリーズになります。今回は Part1 で紹介された内容をまとめていきます。

kou さんがサクッと解説してくださっている動画は、こちらになります。

遭遇した問題

今回は、Apache Arrow をビルドする中で遭遇した下記のエラーになります。

% cmake -S cpp -B cpp.build --preset ninja-debug-maximal -DCMAKE_INSTALL_PREFIX=/tmp/local 
CMake Error at src/arrow/flight/CMakeLists.txt:48 (message):
  Must build Arrow statically to link Flight tests statically

何が起きているのか？

C++ のソースコードをビルドしようとして、必要なライブラリが正しくリンクできないために発生しています。ただ、リンクが何かわかっておらず、よく分かっていないので次はリンクについてみていきます！

リンクとは？

リンクは、C や C++ がライブラリを利用するためのプロセスです。Rubyでライブラリを利用するときには require を使いますが、C や C++ ではリンクというプロセスを通じてライブラリを利用します。リンクには主に2つの形式があります。Static link と Dynamic link です。

`Static link` と `Dynamic link`

Static link と Dynamic link の違いは、同じライブラリを複数のプログラムが利用する違いです。

Dynamic link

Ruby で考えると、複数の gem(ライブラリ)が同じ gem を利用する場合、例えば Rails で言うと 1 つの Active Support の実体を他の gem が共有して利用する状態が Dynamic link に相当します。なので Active Support のバージョンを更新すると、共有して利用していた他のライブラリ全てが影響を受けます。

Static link

一方、各 gem がそれぞれ Active Support を持っている状態は、Static link に近いと考えられます。それぞれのライブラリが独自のActive Supportを保持しているため、他のライブラリが保持している Active Support を更新しても、それが他のライブラリに影響を及ぼすことはありません。

実際に Ruby で Static Link をやっているライブラリっているの？ Rubygems がやっています。

対応策

正しくライブラリがリンクされるように修正する必要があります。ただ、今回の Ruby バインディングの開発では、スタティックにリンクする必要や対象のライブラリは必要ではないので、エラーが起きているライブラリを使わずにビルドすることで回避します。具体的には下記の 2 つのオプションをつけます。

-DARROW_FLIGHT=OFF
-DARROW_BUILD_TESTS=OFF

% cmake -S cpp -B cpp.build --preset ninja-debug-maximal -DARROW_FLIGHT=OFF -DARROW_BUILD_TESTS=OFF -DCMAKE_INSTALL_PREFIX=/tmp/local
CMake Error at src/arrow/flight/CMakeLists.txt:48 (message):
  Must build Arrow statically to link Flight tests statically

Apache Arrow の Ruby バインディングに新機能を追加する準備編

2023-05-31T14:59:18+00:00

何をやりたいか

Apache Arrow の Rubyバインディング（Red Arrow）に新機能を追加したい。
具体的にはこちらの [Ruby] Add Arrow::RecordBatch#each_raw_recordを解決したい。

登場人物

Apache Arrow
- 実装言語: C++
- 効率的なデータ分析を可能にする、言語に依存しない列指向メモリフォーマットを提供するツール
Red Arrow
- 実装言語: Ruby, C++
- Apache Arrow を Ruby から使えるようにする Ruby の拡張ライブラリ
CMake
- CMakeはクロスプラットフォームで柔軟性の高いビルドシステムです
- Apache Arrow C++ のコンフィグレーションに利用されます
Meson
- 高速でユーザーフレンドリーなクロスプラットフォームのビルドシステム
- Apache Arrow GLib のコンフィグレーションに利用されます
Ninja
- 高速なビルドシステムで、大規模なソフトウェアプロジェクトのコンパイルを効率的に行います
- CMakeやMesonなどのビルドシステムと組み合わせて、ビルドの設定と実行を行います
- Apache Arrow C++ と Apache Arrow GLib のビルドに利用されます

準備としてやること

Red Arrow の機能追加に着手するための開発環境の構築を行なっていく。下記のライブラリに依存しているのでインストールを行なっていく。

Apache Arrow C++ のインストール
Apache Arrow GLib のインストール
Red Arrow のビルド

Ref: https://github.com/apache/arrow/tree/main/ruby/red-arrow#development

Apache Arrow C++ のインストール

基本的には下記に記されている手順通りに Arrow C++ のビルドを進めていく。 +α で教えていただいこともメモとして追記します。

https://arrow.apache.org/docs/developers/cpp/building.html

インストールする際には大きく 3 つのステップがあります。

コンフィグレーション
- ビルドに必要な依存パッケージの準備やビルド手順を定義したファイルを生成する
ビルド
- コンフィグレーションで生成されたファイルを元にビルドする
- 具体的には、ソースコードのコンパイルとリンクをする
インストール
- ビルドした成果物をインストールする

事前準備

ビルドに必要なライブラリを Homebrew を利用していインストールします。

% git clone https://github.com/apache/arrow.git
% cd arrow
% brew update && brew bundle --file=cpp/Brewfile

コンフィグレーション

ビルドに必要な依存パッケージの準備（場所の把握やインストール）やビルド手順を定義したファイルを生成していきます。今回は、普通にコンフィグレーションするだけではなくいくつかのオプションを追記しています。

% cmake -S cpp -B ./cpp.build --preset ninja-debug-maximal -DARROW_CUDA=OFF -DARROW_SKYHOOK=OFF -DCMAKE_INSTALL_PREFIX=/tmp/local

-S cpp
- コンフィグレーションする際に利用するソースディレクトリを指定
- 今回は、cpp 配下を利用し、コンフィグレーションしていきます
-B ./cpp.build
- コンフィグレーションしビルドする際に利用する成果物を配置するディレクトリを指定
- xxx.build の命名は、kou さんのオススメです
  - ビルド元がわかりやすい && ビルド用ディレクトリであることがわかりやすい
--preset ninja-debug-maximal
- どのようにコンフィグレーションするかを指定できるオプションが提供されています
- 今回は、ビルドツールに Ninja を利用し、全てを有効化にしたデバッグビルドを行う設定にしています
-DCMAKE_INSTALL_PREFIX=/tmp/local
- ビルドした際の成果物のインストール先を指定します
- 今回は、/tmp/local　を指定しています
-DARROW_CUDA=OFF -DARROW_SKYHOOK=OFF
- Arrow C++ が提供する特定の機能に対するフラグになります
- 今回は、CUDA　との連携機能と Skyhook 機能を無効にしています
  - ビルド時にエラーになったため（今回拡張したい機能では不要なため許容しています）
- ref: https://arrow.apache.org/docs/developers/cpp/building.html#optional-components

ビルド

コンフィグレーションで準備されたビルド環境を元にビルドを行なっていきます。

% cmake --build ./cpp.build

--build ./cpp.build
- ビルド対象のディレクトリを指定します
- 今回は、cpp.build 配下を指定しています
  - なぜなら、コンフィグレーション時に -B オプションで指定したため

インストール

ビルドされた成果物をインストールしていきます。今回は、コンフィグレーション時に指定した -DCMAKE_INSTALL_PREFIX=/tmp/local にインストールします。

% ninja -C cpp.build install

-C cpp.build
- Ninja を実行するディレクトリを指定できます
- 今回は、ビルドした cpp.build を対象にしてインストールをします

ここまでで、Apache Arrow C++ のインストールが完了です。お疲れ様です！

Apache Arrow GLib のインストール

基本的には、Arrow C++ と同様の下記の 3 つのステップでインストールしていきます。下記の情報を元に進めていきます。

https://github.com/apache/arrow/blob/main/c_glib/README.md

コンフィグレーション
ビルド
インストール

事前準備

ビルドに必要なライブラリを Homebrew を利用していインストールします。

% brew update && brew bundle --file=c_glib/Brewfile

コンフィグレーション

% meson setup ./c_glib.build ./c_glib --prefix /tmp/local --debug --pkg-config-path /tmp/local/lib/pkgconfig

setup ./c_glib.build ./c_glib
- setup は、ビルド用の成果物を配置するディレクトリと、コンフィグレーションする元になるディレクトリを指定します
--prefix /tmp/local
- ビルドした際の成果物のインストール先を指定します
--debug
- ビルド時にデバック情報を生成するようにコンパイラに指示します
--pkg-config-path /tmp/local/lib/pkgconfig
- pkg-config がライブラリを探す際に探索するパスを指定できます
- 今回は、依存ライブラリとして Arrow C++ を利用するので、前述のインストール先を参照しています

ビルド

Meson でコンフィグレーションされたビルド環境を元にビルドを行なっていきます。

% ninja -C c_glib.build

-C cpp.build
- Ninja を実行するディレクトリを指定できます
- 今回は、コンフィグレーションで準備したビルドディレクトリ c_glib.build を対象にして、ビルドします

インストール

ビルドされた成果物をインストールしていきます。今回は、コンフィグレーション時に指定した /tmp/local にインストールします。

% ninja -C c_glib.build install

オプションに関しては、上記で説明しているので省くね

ここまでで、Apache Arrow GLib のインストールが完了です。お疲れ様です！

Red Arrow のビルド

前述の Apache Arrow C++ と Apache Arrow GLib のインストールと同様の手順で進めていきます。今回は、インストールする必要がないので、2 ステップになります。

コンフィグレーション
ビルド

事前準備

Red Arrow のビルドに必要な gem をインストールしていきます。

% cd ruby; bundle install;
% cd red-arrow; bundle install 

コンフィグレーション

ext/arrow/ 配下の extconf.rb を元にコンフィグレーションを行います。

% cd ext/arrow; ruby extconf.rb

ビルド

コンフィグレーションによって生成された Makefile を元にビルドを行います。

% make

テスト

最後に Red Arrow が正常にビルドされたかをテストします。

% pwd
/arrow/ruby/red-arrow
% bundle exec rake test

無事にテストが完了したら、Red Arrow のビルドですおめでとうございます！

Otegami Letter

Apache Arrow の Ruby バインディングに新機能を追加する 実装編 Part4

最初に

記事の位置付け

前回までのあらすじ

おおまかな作業の流れ

1. Ruby C API で Ruby のメソッドを定義する

2. Ruby C API で呼び出す C++ のメソッドを定義する

3. 列指向のデータ構造を行指向のデータ構造に変換するための RawRecordsProducer クラスを定義する

4. 変換結果を逐次的に yield して返す RawRecordsProducer#produce の実装する

最後に

Symbol not found in flat namespace - arrow.bundle(LoadError)

最初に

遭遇した問題

対応策

マングリングとは？

デマングルとは？

対応策（詳細編）

バイナリファイル内からシンボルを探す

個人的に思ったこと

Apache Arrow の Ruby バインディングに新機能を追加する 実装編 Part3

最初に

記事の位置付け

前回までのあらすじ

内部実装を読んでいくための入り口を決めよう

Arrow::Table#raw_records の実装を紐解いていく

red_arrow::table_raw_records

RawRecordsBuilder#build

RawRecordsBuilder::VISIT(この表記は正確ではないですmm)

RawRecordsBuilder convert

Apache Arrow の Ruby バインディングに新機能を追加する 実装編 Part2

最初に

記事の位置付け

前回までのあらすじ

C レイヤーでの実装の流れを掴む

拡張ライブラリを require して読み込む

メソッドを定義する

yield してイテレートする

Apache Arrow の Ruby バインディングに新機能を追加する 実装編 Part1

最初に

前回までのあらすじ

どんな機能を追加したいの？

どんな時に嬉しいのか？

どのように進めていくのか

1. 追加したい機能を Ruby で実装してイメージを掴む

Incompatible Library Version Error

最初に

遭遇した問題

対応策

何が起きているのか？

互換性のある libruby は何なのか確認する

DYLD Environment Variables

最初に

遭遇した問題

対応策

何が起きているのか？

DYLD_LIBRARY_PATH に libarrow-glib.1300.dylib のパスを指定する

MacOS 上で DYLD_LIBRARY_PATH は特別な環境変数である

ruby command はサブプロセスで実行されている？

Static link と Dynamic Link

最初に

遭遇した問題

何が起きているのか？

リンクとは？

Static link と Dynamic link

Dynamic link

Static link

対応策

Apache Arrow の Ruby バインディングに新機能を追加する 準備編

何をやりたいか

登場人物

準備としてやること

Apache Arrow C++ のインストール

事前準備

コンフィグレーション

ビルド

インストール

Apache Arrow GLib のインストール

事前準備

コンフィグレーション

Apache Arrow の Ruby バインディングに新機能を追加する実装編 Part4

Apache Arrow の Ruby バインディングに新機能を追加する実装編 Part3

Apache Arrow の Ruby バインディングに新機能を追加する実装編 Part2

拡張ライブラリを `require` して読み込む

Apache Arrow の Ruby バインディングに新機能を追加する実装編 Part1

互換性のある `libruby` は何なのか確認する

DYLD_LIBRARY_PATH に `libarrow-glib.1300.dylib` のパスを指定する

MacOS 上で `DYLD_LIBRARY_PATH` は特別な環境変数である

`Static link` と `Dynamic link`

Apache Arrow の Ruby バインディングに新機能を追加する準備編