12.5. C 言語関数

12.5.1. 動的ロード

特定のロード可能オブジェクト内のユーザ定義の関数がバックエンドセッションで最初に呼び出されると、動的ローダは、その関数を呼び出すことができるように、オブジェクトファイルをメモリ内に読み込みます。そのため、ユーザ定義の C 関数用の CREATE FUNCTION はその関数について、ロード可能オブジェクトファイルの名前とオブジェクトファイル中内の呼び出される特定の関数の C 名称(リンクシンボル)2つの情報を指定しなければなりません。C 名称が明示的に指定されなかった場合、SQL における関数名と同じものと仮定されます。

CREATE FUNCTION コマンドで与えられた名前に基づいて、共有オブジェクトファイルの場所を見つける際に以下のアルゴリズムが使用されます。

1. 名前が絶対パスの場合、指定されたファイルが読み込まれます。

2. 名前が $libdir という文字列から始まる場合、その部分は PostgreSQL パッケージのライブラリディレクトリで置き換えられます。このディレクトリはビルド時に決定されます。

3. 名前にディレクトリ部分がない場合、そのファイルは dynamic_library_path 設定変数で指定されたパス内から検索されます。

4. 上記以外の場合(ファイルがパス内に存在しない場合や相対ディレクトリ部分をもつ場合)、動的ローダは指定された名前をそのまま使用し、ほとんどの場合は失敗します。(これは現在の作業ディレクトリに依存するため信頼できません。)

ここまでの流れでうまくいかなかった場合、プラットホーム独自の共有ライブラリファイル拡張子が指定された名前に追加され、再度、この流れを試みます。同様に失敗した場合は、読み込みは失敗します。

どの場合でも、CREATE FUNCTION コマンドに与えたファイル名はそのままシステムカタログに保存されます。もし、そのファイルを再度読み込む必要がある場合、同じ処理が適用されます。

共有ライブラリを $libdir から相対的に、もしくは、動的ライブラリパスの通った所に配置することを推奨します。異なる位置に新しいインストレーションを配置する場合にバージョンアップを簡単にします。 $libdir が示す実際のディレクトリは pg_config --pkglibdir コマンドを使用することで分かります。

12.5.2. C言語関数の基本型

Table 12-1 は、 PostgreSQL にロードされるC言語関数の引数で必要とされるC言語の型の一覧です。 "定義場所"列では、型定義を取り出すためにインクルードしなければならないヘッダファイルを示しています。(実際の定義は一覧中のファイルとは異なる可能性があります。ユーザは定義されたインタフェースを stick することを推奨されています。) postgres.h には必ず必要になる多くのものが宣言されていますので、ソースファイルの中で必ず始めにこのファイルをインクルードしなければならないことに注意して下さい。

PostgreSQLの内部では、基本型を「blob of memory（メモリの斑点）」とみなしています。ある型について定義したユーザー定義関数は、同様にPostgreSQLがその型をどのように実装するかを定義しています。つまり、PostgreSQLはデータをディスクに保存し、ディスクからデータを受取り、ユーザー定義関数でそのデータを入力値として受け取り、処理/出力するために使用します。基本型は下記の3つのいずれかの内部フォーマットを使用しています。

• 固定長の値渡し

• 固定長の参照渡し

• 可変長の値渡し

値渡しを使用する型は、1、2、4バイト長のも可能です(使用するマシンの sizeof(Datum) が 8 の場合は 8 バイトも可能です)。データ型を定義する際、その型がすべてのアーキテクチャにおいて同一の大きさ（バイト数）となるように定義することに注意してください。たとえば、long型はマシンによっては 4 バイトであったり、8 バイトであったりして危険ですが、int型はほとんどのUnixマシンでは4バイトです。Unix マシンにおける int4 の理論的な実装は以下のようになります。

/* 4 バイト整数、値渡し */
typedef int int4;

PostgreSQL は自動的にその整数型が本当にadvertise した大きさを持つように、figure out します。

一方、任意の大きさの固定長の型は参照として引き渡すことが可能です。下記の、PostgreSQLの型の実装サンプルを参照してください。

/* 16-バイト構造体、参照渡し */
typedef struct
{
    double  x, y;
} Point;

それらの型のポインタのみがPostgreSQL関数の入出力時に使用できます。それらの型の値を返すためには、palloc()を使用して正しい大きさのメモリ領域を割り当て、そのメモリ領域に値を入力し、それのポインタを返します（あるいは、ポインタを返すことによって同じ型の入力値を返すことも可能です。しかし、参照として渡すものの入力値の内容は決して変更しないでください）。

最後に、すべての可変長型は参照として引き渡す必要があります。また、すべての可変長型は正確に4バイトのlengthフィールドから始まる必要があり、その型に格納されるすべてのデータはlengthフィールドのすぐ後のメモリ領域に置かれる必要があります。lengthフィールドはその構造体の総長です（つまり、lengthフィールドそのものもその大きさに含まれます）。text型を定義するには、下記のように行えます。

typedef struct {
    int4 length;
    char data[1];
} text;

ここで宣言されたデータフィールドは、明らかにすべての取り得る文字列を保持できる長さではありません。 C言語では可変長の構造体を定義することは不可能ですので、 C コンパイラは配列の添字の範囲検査を行なわないという事実に依存します。もし正しい長さで宣言されたとすると、必要な領域量を割り当て、配列としてアクセスするだけです。(この手法に不慣れであるのならば、PostgreSQL サーバのプログラミングにより delve する前に C プログラムの入門書を読んで下さい。)可変長型を操作する時、正確な大きさのメモリを割当て、length フィールドを正確に設定することに注意する必要があります。例えば、40バイトを text 構造体に保持させたい場合、下記のようなコードを実行します。

#include "postgres.h"
...
char buffer[40]; /* our source data */
...
text *destination = (text *) palloc(VARHDRSZ + 40);
destination->length = VARHDRSZ + 40;
memcpy(destination->data, buffer, 40);
...

VARHDRSZ は sizeof(int4) と同一ですが、可変長型のオーバヘッド分の大きさを参照する時には、VARHDRSZ マクロを使用する方が好ましい形式とみなされています。

これで基本型用のすべてのあり得る構造体についての説明が完了しましたので、実際の関数の例をいくつか示します。

12.5.3. C言語関数のためのVersion-0の呼び出し規約

まず最初に、現在は非推奨ですが理解しやすいので、"古いスタイル"の呼び出し規約を記述します。Version-0メソッドでは、C言語関数の引数と結果は、通常の C のプログラムの記述の方法と同じような形式で行いますが、上記の説明のように、各 SQLのデータ型を示すC言語を使用には注意してください。

以下にいくつか例を示します。

#include "postgres.h"
#include <string.h>

/* 値渡し */
         
int
add_one(int arg)
{
    return arg + 1;
}

/* 固定長の参照渡し */

float8 *
add_one_float8(float8 *arg)
{
    float8    *result = (float8 *) palloc(sizeof(float8));

    *result = *arg + 1.0;
       
    return result;
}

Point *
makepoint(Point *pointx, Point *pointy)
{
    Point     *new_point = (Point *) palloc(sizeof(Point));

    new_point->x = pointx->x;
    new_point->y = pointy->y;
       
    return new_point;
}

/* 可変長の参照渡し */

text *
copytext(text *t)
{
    /*
     * VARSIZE は構造体の総長をバイト数で表したものです。
     */
    text *new_t = (text *) palloc(VARSIZE(t));
    VARATT_SIZEP(new_t) = VARSIZE(t);
    /*
     * VARDATA は構造体のデータ領域へのポインタです。
     */
    memcpy((void *) VARDATA(new_t), /* destination */
           (void *) VARDATA(t),     /* source */
           VARSIZE(t)-VARHDRSZ);    /* how many bytes */
    return new_t;
}

text *
concat_text(text *arg1, text *arg2)
{
    int32 new_text_size = VARSIZE(arg1) + VARSIZE(arg2) - VARHDRSZ;
    text *new_text = (text *) palloc(new_text_size);

    VARATT_SIZEP(new_text) = new_text_size;
    memcpy(VARDATA(new_text), VARDATA(arg1), VARSIZE(arg1)-VARHDRSZ);
    memcpy(VARDATA(new_text) + (VARSIZE(arg1)-VARHDRSZ),
           VARDATA(arg2), VARSIZE(arg2)-VARHDRSZ);
    return new_text;
}

上のコードが funcs.c というファイルに用意され、共有オブジェクトとしてコンパイル済みであるとすると、以下のようなコマンドで PostgreSQL の関数を定義することができます。

CREATE FUNCTION add_one(int4) RETURNS int4
     AS 'PGROOT/tutorial/funcs' LANGUAGE C
     WITH (isStrict);

-- add_one() SQL 関数名をオーバライドしていることに注意
CREATE FUNCTION add_one(float8) RETURNS float8
     AS 'PGROOT/tutorial/funcs',
        'add_one_float8'
     LANGUAGE C WITH (isStrict);

CREATE FUNCTION makepoint(point, point) RETURNS point
     AS 'PGROOT/tutorial/funcs' LANGUAGE C
     WITH (isStrict);
                         
CREATE FUNCTION copytext(text) RETURNS text
     AS 'PGROOT/tutorial/funcs' LANGUAGE C
     WITH (isStrict);

CREATE FUNCTION concat_text(text, text) RETURNS text
     AS 'PGROOT/tutorial/funcs' LANGUAGE C
     WITH (isStrict);

ここで、PGROOT は PostgreSQL のソースツリーの絶対パスを意味します。(AS 句中では単に 'funcs' を使用し、後で PGROOT/tutorial を検索パスに追加する方がより良い方法です。どの場合でも、 .so や .sl が一般的に使用される、共有ライブラリ用のシステム独特の拡張子を省略することができます。)

ここで、関数を"厳密(strict)"と指定していることに注目してください。それは、もし入力された値がNULLであった場合に、システムが自動的に返り値もNULLであるとみなすことを意味します。これを行うことによって、関数のコードで入力値がNULLであるかどうかのチェックを行う必要がなくなります。これがなければ、各参照渡しの要素に対してそれがNULLのポインタであるかどうかのチェックを行うなどの、NULLの明示的なチェックを行う必要性が出てきます（値渡しに関しては、チェックを行う方法は存在しません）。

これらの呼び出し規約は容易ですが、この方法は、int型のより小さいデータ型を引き渡す部分で問題を抱えているアーキテクチャでは、移植性の面ではあまり優れていません。また、関数の結果としてNULLを返す簡単な方法はありません。その上、引数としてNULLを処理する方法としては、関数を精密なものにする以外方法はありません。次に説明のあるVersion-1の規約ではこれらの問題が解決されています。

12.5.4. C言語関数のためのVersion-1の呼び出し規約

Version-1の呼び出し規約では、引数と結果の引き渡しの複雑さをなくすためにマクロを使用しています。Version-1関数のC言語宣言は必ず下記のように行います。

Datum funcname(PG_FUNCTION_ARGS)

また、以下のマクロの呼び出しが必ず同じソースファイルに書かれている必要があります（規約では、関数の直前で書かれています）。

PG_FUNCTION_INFO_V1(funcname);

現在 PostgreSQL ではすべての内部関数は Version-1 であると認識するので、このマクロの呼び出しは 内部言語関数では必要ありません。しかし、動的にロードされる関数では 必要です。

Version-1関数では、それぞれの実際の引数は、引数の型に合った PG_GETARG_xxx() マクロを使用して取り出され、結果は戻り値の型に合った PG_RETURN_xxx() マクロを使用して返されます。

上記と同じ関数をVersion-1形式で記述したものを以下に示します。

#include "postgres.h"
#include <string.h>
#include "fmgr.h"

/* 値渡し */

PG_FUNCTION_INFO_V1(add_one);
         
Datum
add_one(PG_FUNCTION_ARGS)
{
    int32   arg = PG_GETARG_INT32(0);

    PG_RETURN_INT32(arg + 1);
}

/* 固定長の参照渡し */

PG_FUNCTION_INFO_V1(add_one_float8);

Datum
add_one_float8(PG_FUNCTION_ARGS)
{
    /* FLOAT8 用のマクロは参照渡しという性質を隠します */
    float8   arg = PG_GETARG_FLOAT8(0);

    PG_RETURN_FLOAT8(arg + 1.0);
}

PG_FUNCTION_INFO_V1(makepoint);

Datum
makepoint(PG_FUNCTION_ARGS)
{
    /* ここの Point 型の参照渡しという性質は隠されていません */
    Point     *pointx = PG_GETARG_POINT_P(0);
    Point     *pointy = PG_GETARG_POINT_P(1);
    Point     *new_point = (Point *) palloc(sizeof(Point));

    new_point->x = pointx->x;
    new_point->y = pointy->y;
       
    PG_RETURN_POINT_P(new_point);
}

/* 可変長の参照渡し */

PG_FUNCTION_INFO_V1(copytext);

Datum
copytext(PG_FUNCTION_ARGS)
{
    text     *t = PG_GETARG_TEXT_P(0);
    /*
     * VARSIZE は構造体の総長をバイト数で表したものです。
     */
    text     *new_t = (text *) palloc(VARSIZE(t));
    VARATT_SIZEP(new_t) = VARSIZE(t);
    /*
     * VARDATA は構造体のデータ領域へのポインタです。
     */
    memcpy((void *) VARDATA(new_t), /* destination */
           (void *) VARDATA(t),     /* source */
           VARSIZE(t)-VARHDRSZ);    /* how many bytes */
    PG_RETURN_TEXT_P(new_t);
}

PG_FUNCTION_INFO_V1(concat_text);

Datum
concat_text(PG_FUNCTION_ARGS)
{
    text  *arg1 = PG_GETARG_TEXT_P(0);
    text  *arg2 = PG_GETARG_TEXT_P(1);
    int32 new_text_size = VARSIZE(arg1) + VARSIZE(arg2) - VARHDRSZ;
    text *new_text = (text *) palloc(new_text_size);

    VARATT_SIZEP(new_text) = new_text_size;
    memcpy(VARDATA(new_text), VARDATA(arg1), VARSIZE(arg1)-VARHDRSZ);
    memcpy(VARDATA(new_text) + (VARSIZE(arg1)-VARHDRSZ),
           VARDATA(arg2), VARSIZE(arg2)-VARHDRSZ);
    PG_RETURN_TEXT_P(new_text);
}

CREATE FUNCTIONコマンドは、Version-0と同じものです。

一見 Version-1 のコーディング規約は無意味なものに見えるかもしれませんが、マクロが必要のない情報を隠蔽しているので、多数の改良が行われています。たとえば、add_one_float8のコードでは、 float8 が参照渡しであることを意識する必要がなくなっています。また別の例としては、可変長型のGETARG マクロは "toasted" 値（圧縮、または行外）の取り扱う必要性を隠蔽します。上記にある、古いスタイルの copytext 関数と concat_text 関数は、toasted値が存在した場合、入力にpg_detoast_datum()を使用しないので、実際は誤ったものとなります（古いスタイルの動的にロードされる関数のハンドラは、現在、この問題に対処していますが、Version-1関数で実行可能なことよりも劣ります）。

Version-1関数の1つの大きな改善点は、NULLの入力/結果の処理能力です。PG_ARGISNULL(n) マクロにより関数は各入力がNULLであるかどうかのテストを行なうことができます（これは、"厳密"と宣言されていない関数でのみ必要です）。 PG_GETARG_xxx()マクロでは、入力された引数は始まり値を0として数え上げられます。引数が NULL でないことを確認するまでは、 PG_GETARG_xxx()の実行は控えなければなりません。結果としてNULLを返す場合は、PG_RETURN_NULL()を実行します。これは、厳密な関数と厳密でない関数の両方で使用可能です。

Version-1 関数呼び出し規約では、"セット(set)" の結果を返すこと、および、トリガ関数と手続型言語の呼び出しハンドラを実装することができます。また、Version-1 コードは、ANSI Cの制約が関数呼び出しプロトコルで守られているので、Version-0よりも移植性があります。詳細はソースディストリビューションのsrc/backend/utils/fmgr/README を参照してください。

12.5.5. 複合型を使用したC言語関数

複合型では、Cの構造体のような固定のレイアウトがありません。複合型のインスタンスはヌルフィールドを持つ可能性があります。更に、複合型で、継承階層の一部であるものは同じ継承の階層の他のメンバとは異なるフィールドを持つ可能性もあります。そのため、PostgreSQLはC言語から複合型のフィールドにアクセスするための手続きのインターフェイスを提供します。 PostgreSQLが行の集合を処理するにつれ、各行は不明瞭なTUPLE型の構造体として引き渡されます。問い合わせを答える以下のような関数を書こうとしていると仮定します。

SELECT name, c_overpaid(emp, 1500) AS overpaid
FROM emp
WHERE name = 'Bill' OR name = 'Sam';

上記の問い合わせでは、c_overpaid を下記のように定義することができます。

#include "postgres.h"
#include "executor/executor.h"  /* for GetAttributeByName() */

bool
c_overpaid(TupleTableSlot *t, /* the current row of EMP */
           int32 limit)
{
    bool isnull;
    int32 salary;

    salary = DatumGetInt32(GetAttributeByName(t, "salary", &isnull));
    if (isnull)
        return (false);
    return salary > limit;
}

/* version-1 コーディングでは、上の関数は以下のようになります。*/

PG_FUNCTION_INFO_V1(c_overpaid);

Datum
c_overpaid(PG_FUNCTION_ARGS)
{
    TupleTableSlot  *t = (TupleTableSlot *) PG_GETARG_POINTER(0);
    int32            limit = PG_GETARG_INT32(1);
    bool isnull;
    int32 salary;

    salary = DatumGetInt32(GetAttributeByName(t, "salary", &isnull));
    if (isnull)
        PG_RETURN_BOOL(false);
    /* 給与が空の場合は、代わりに、 PG_RETURN_NULL() を行なうように変更する方がいいかも知れません */

    PG_RETURN_BOOL(salary > limit);
}

GetAttributeByNameは、現在の行から属性を返す、PostgreSQLシステム関数です。これには3つの引数があります。それらはTupleTableSlot*型が関数に引き渡されたときの引数、求められた属性の名前、属性がNULLであるかどうかの返りパラメータです。GetAttributeByNameは適切なDatumGetXXX()マクロを使用して適切なデータ型に変換可能なDatum型の値を返します。

下記のコマンドは、PostgreSQLにc_overpaid関数を認識させるものです。

CREATE FUNCTION c_overpaid(emp, int4) 
RETURNS bool
AS 'PGROOT/tutorial/funcs' 
LANGUAGE C;

C 関数内で新しい行を作成したり、現存する行を変更させたりする方法もありますが、ここで述べるには難易度がとても高いので、省略します。例としてバックエンドのソースコードを参考にしてください。

12.5.6. コードの作成

ここからは、より難易度の高い、プログラミング言語関数の説明となります。注意してほしいのは、この節の主旨は、プログラマを養成することではないということです。 PostgreSQL用のC関数を書く前に、C言語についてよく理解している必要があります（ポインタやmallocメモリ管理も含みます）。 C言語以外の言語で記述した関数を PostgreSQLに組み込みむことは可能ですが、たとえばFORTRANやPascalといった言語はC言語と同じ 呼び出し規約ではないので、多くの場合、(可能であったとしても)困難です。それはつまり、他の言語では同じ方法で引数を渡したり結果を返すことを行わないということです。このため、プログラミング言語関数はC言語で書かれているものと仮定します。

C関数を作成するときの基本的な規則は下記のものです。

• pg_config --includedir-server を使用して、使用中のシステム(もしくはユーザが実行するシステム)にて PostgreSQL サーバのヘッダファイルがインストールされた場所を見つけます。 PostgreSQL 7.1 では、--includedir オプションを使用しなければなりません。(pg_config は認識できないオプションが与えられた時に非 0 のステータスで終了します。)7.1 より前のリリースでは、推測する必要がありますが、現在の呼出し規約が導入される前のものですので、これらのリリースをサポートしようとは考えないでしょう。

• メモリを割り当てる際、Cライブラリのmallocとfreeではなく、PostgreSQLのpallocとpfreeを使用してください。 pallocで割り当てられたメモリは各トランザクションの終わりに自動的に解放され、メモリリークを防ぎます。

• memsetまたはbzeroを使用して、構造体を必ず0クリアにしてください。複数のルーチン（ハッシュアクセスメソッド、ハッシュ結合、ソートアルゴリズム）は構造体に含まれている生のビットの関数を計算します。構造体のすべてのフィールドを初期化しても必要のない値を持っている、数バイトの位置揃え用のパディング(構造体内の穴)が存在する可能性があります。

• ほとんどのPostgreSQLの内部型は postgres.hに宣言されています。一方、関数管理インターフェイス（PG_FUNCTION_ARGSなど）はfmgr.hで宣言されています。したがって、少なくともこの2つのファイルをインクルードする必要があります。移植性に関する理由により、postgres.h をその他のシステムヘッダファイル、ユーザヘッダファイルよりも 先にインクルードしておくことが最善です。 postgres.hをインクルードすることは elog.h、palloc.hもインクルードすることになります。

• オブジェクトファイルで定義されているシンボル名は互いに、および、PostgreSQLサーバの実行ファイルで定義されているものと異なっている必要があります。これに関するエラーが表示される場合は、関数名または変数を変更する必要があります。

• PostgreSQLに動的にロードできるようにオブジェクトコードをコンパイル/リンクするときには、特別なフラグが必要となります。その方法を特有のオペレーティングシステムで行う場合の詳細は Section 12.5.7を参照してください。

12.5.7. 動的にロードされる関数のコンパイルとリンク

C で書かれた PostgreSQL の拡張関数を使うためには、サーバが動的にロードできるように特別な方法でコンパイルとリンクを行う必要があります。正確には 共有ライブラリを作る必要があります。

詳しい情報はオペレーティングシステムのドキュメント、特に C コンパイラ cc と、リンクエディタ ld のマニュアルページを参照してください。さらに、PostgreSQL のソースコードの contrib ディレクトリにいくつか実例があります。しかしもしこれらの例に頼ると PostgreSQL ソースコードの有効性に依存したモジュールが作られてしまいます。

共有ライブラリの作成は実行プログラムのリンクと似ています。まずソースファイルがオブジェクトファイルにコンパイルされ、そのオブジェクトファイル同士がリンクされます。これらのオブジェクトファイルは位置独立なコード （PIC）として作られる必要があります。それは概念的には、実行プログラムから呼び出されるときにメモリの適当な場所に置くことができるということです。（実行プログラムとして作られたオブジェクトファイルはそのようにはコンパイルされません。）共有ライブラリをリンクするコマンドは実行プログラムのリンクと区別するための特別なフラグがあります。少なくとも理論上ではそのようになっています。他のシステムではもっと醜い実際が見受けられます。

次の例ではソースコードはファイル foo.c にあると仮定し、 foo.so という共有ライブラリを作るとします。中間のオブジェクトファイルは特別な記述がない限り foo.o と呼ばれます。共有ライブラリは 1 つ以上のオブジェクトファイルを持つことができますが、ここでは 1 つしか使いません。

これで完成した共有ライブラリファイルは Postgres にロードすることができます。CREATE FUNCTION コマンドにファイル名を指定するときには、中間オブジェクトファイルではなく共有ライブラリファイル名(の名前を与えてください。システムの標準共有ライブラリ拡張（通常 .so あるいは .sl で終わるもの）は CREATE FUNCTION で省略することができ、そして移植性を最も高くするため通常は省略されます。

サーバがライブラリファイルをどこに見つけるかに関しては Section 12.5.1 を見直してください。