9.5. C 言語関数

9.5.1. 動的ロード

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

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

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

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

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

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

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

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

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

9.5.2. C言語関数の基本型

Table 9-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 マクロを使用する方が好ましい形式とみなされています。

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

9.5.3. C言語関数のためのVersion0の呼び出し規約

まず最初に、現在は非推奨ですが理解しやすいので、"古いスタイル"の呼び出し規約を記述します。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の規約ではこれらの問題が解決されています。

9.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()を実行します。 これは、厳密な関数と厳密でない関数の両方で使用可能です。

新しい形式のインタフェースでは、その他のオプションとして PG_GETARG_xxx() マクロの変形を 2 つ提供しています。 1 つ目の PG_GETARG_xxx_COPY() によって、安全に書き込むことができる指定パラメータのコピーが確実に返されます。 (通常のマクロは、物理的にテーブルに格納されている値へのポインタを返すことがあるので、書き込むべきではありません。PG_GETARG_xxx_COPY() マクロを使うことで安心して結果へ書き込むことができます。)

2 つ目の変形は、パラメータを 3 つ取る PG_GETARG_xxx_SLICE() マクロから成ります。 1 つ目はパラメータの数 (上記のとおり) です。 2 つ目と 3 つ目は、オフセットと返されるセグメントの長さです。 オフセットはゼロから始まり、負の長さは残りの値を返すことを要求します。 これらのルーチンを使用すると、ストレージの型が「external」(外部) である大きな値の一部へアクセスする際に非常に効果的です。 (列のストレージの型は ALTER TABLE tablename ALTER COLUMN colname SET STORAGE storagetype を使用して指定できます。 ストレージの型は、plain、external、extended、または main のいずれかです。)

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

9.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;

9.5.6. テーブル関数 API

テーブル関数 API はユーザ定義の C 言語テーブル関数を作成する際の補助として使用します (Section 9.7)。 テーブル関数は、行のセットを生成する関数で、基本 (スカラ) データ型あるいは複合 (複数列) データ型のどちらかです。 この API は、複合データ型を返すためのサポートと複数行を返すためのサポート (set returning functions、すなわち SRF) という 2 つの主要なコンポーネントに分かれます。

テーブル関数 API はマクロと関数を使用して、複合データ型をビルドして複数の結果を返す際の複雑さを取り除きます。 テーブル関数は、先に説明した version-1 呼び出し規約の従わなくてはなりません。 さらに、ソースファイルには以下が含まれている必要があります。

#include "funcapi.h"

typedef struct AttInMetadata
{
    /* TupleDesc がいっぱい */
    TupleDesc       tupdesc;

    /* 属性の型の入力関数の配列 finfo */
    FmgrInfo       *attinfuncs;

    /* 属性の型の配列 typelem */
    Oid            *attelems;

    /* 属性の配列 typmod */
    int32    	   *atttypmods;
}	AttInMetadata;

TupleDesc RelationNameGetTupleDesc(const char *relname)

TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases)

AttInMetadata *TupleDescGetAttInMetadata(TupleDesc tupdesc)

TupleTableSlot *TupleDescGetSlot(TupleDesc tupdesc)

HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values)

TupleGetDatum(TupleTableSlot *slot, HeapTuple tuple)

typedef struct
{
    /*
     * 既に行われた呼び出しの回数。
     * 
     * SRF_FIRSTCALL_INIT() によって call_cntr が 0 に初期化され、
     * SRF_RETURN_NEXT() が呼びだれる度に増分されます。
     */
    uint32 call_cntr;

    /*
     * 省略可能 : 呼び出しの最大数
     *
     * max_calls は、便宜上用意されているだけで、設定は省略可能です。
     * 設定されていなければ、関数が終了したことを知るための別の方法を
     * 用意する必要があります。
     */
    uint32 max_calls;

    /*
     * 省略可能 : 結果スロットへのポインタ
     * 
     * スロットはタプルを返す際 (たとえば複合データ型) に使用され、
     * 基本 (スカラ) データ型を返す場合には必要ありません。
     */
    TupleTableSlot *slot;

    /*
     * 省略可能 : 様々なユーザによるコンテキスト情報へのポインタ
     * 
     * user_fctx は、関数の呼び出し間の任意のコンテキスト情報
     * を取得するためのユーザ独自の構造へのポインタとして使用されます。
     */
    void *user_fctx;

    /*
     * 省略可能 : 属性型入力メタ情報の配列を含んだ構造へのポインタ

     * 
     * attinmeta はタプルを返す際 (たとえば複合データ型) に使用され、
     * 基本データ型 (スカラ) を返す場合には必要ありません。 
     * BuildTupleFromCStrings() を使用して返されるタプルを作成する場合にのみ

     * 必要です。
     */
    AttInMetadata *attinmeta;

    /*
     *  複数の呼び出しで使用可能な構造に使われるメモリコンテキスト
     *
     * multi_call_memory_ctx は、SRF_FIRSTCALL_INIT() によって自動的に設定され、
     * SRF_RETURN_DONE() がクリーンアップの際に使用します。 
     * これは SRF の複数呼び出しで再利用されるすべてのメモリについて
     最も適切なメモリコンテキストです。
     */
    MemoryContext multi_call_memory_ctx;
} FuncCallContext;

SRF_IS_FIRSTCALL()

SRF_FIRSTCALL_INIT()

SRF_PERCALL_SETUP()

SRF_RETURN_NEXT(funcctx, result)

SRF_RETURN_DONE(funcctx)

Datum
my_Set_Returning_Function(PG_FUNCTION_ARGS)
{
    FuncCallContext  *funcctx;
    Datum             result;
    MemoryContext     oldcontext;
    [user defined declarations]

    if (SRF_IS_FIRSTCALL())
    {
        funcctx = SRF_FIRSTCALL_INIT();
        oldcontext = MemoryContextSwitchTo(funcctx->multi_call_memory_ctx);
        /* 1 度限りのセットアップコードがここに入ります: */
        [user defined code]
        [if returning composite]
            [build TupleDesc, and perhaps AttInMetadata]
            [obtain slot]
            funcctx->slot = slot;
        [endif returning composite]
        [user defined code]
        MemoryContextSwitchTo(oldcontext);
    }

    /* 毎回実行するセットアップコードがここに入ります: */
    [user defined code]
    funcctx = SRF_PERCALL_SETUP();
    [user defined code]

    /* これは、終了したかどうかをテストする方法の 1 つです: */
    if (funcctx->call_cntr < funcctx->max_calls)
    {
        /* ここで、別の項目を返します: */
        [user defined code]
        [obtain result Datum]
        SRF_RETURN_NEXT(funcctx, result);
    }
    else
    {
        /* これで項目を返し終わりました。 あとはクリーンアップするだけです。 */
        [user defined code]
        SRF_RETURN_DONE(funcctx);
    }
}

PG_FUNCTION_INFO_V1(testpassbyval);
Datum
testpassbyval(PG_FUNCTION_ARGS)
{
    FuncCallContext      *funcctx;
    int                  call_cntr;
    int                  max_calls;
    TupleDesc            tupdesc;
    TupleTableSlot       *slot;
    AttInMetadata        *attinmeta;

     /* 関数の最初の呼び出し時にのみ実行 */
     if (SRF_IS_FIRSTCALL())
     {
        MemoryContext	oldcontext;

        /* 呼び出し間パーシスタンス用の関数コンテキストを作成 */
        funcctx = SRF_FIRSTCALL_INIT();

        /* 複数関数呼び出しに適切なメモリコンテキストへの切り替え */
        oldcontext = MemoryContextSwitchTo(funcctx->multi_call_memory_ctx);

        /* 返されるタプルの合計数 */
        funcctx->max_calls = PG_GETARG_UINT32(0);

        /*
         *  a__testpassbyval タプル用のタプル記述を作成
         */
        tupdesc = RelationNameGetTupleDesc("__testpassbyval");

        /* この tupdesc を持つタプルへのスロットの割り当て  */
        slot = TupleDescGetSlot(tupdesc);

        /* 関数コンテキストへのスロットの割り当て */
        funcctx->slot = slot;

        /*
         * 後で未加工の C 文字列からタプルを作成するために必要となる
         * 属性メタデータの生成
         */
        attinmeta = TupleDescGetAttInMetadata(tupdesc);
        funcctx->attinmeta = attinmeta;

        MemoryContextSwitchTo(oldcontext);
    }

    /* すべての関数呼び出しで実行 */
    funcctx = SRF_PERCALL_SETUP();

    call_cntr = funcctx->call_cntr;
    max_calls = funcctx->max_calls;
    slot = funcctx->slot;
    attinmeta = funcctx->attinmeta;
 
    if (call_cntr < max_calls)    /* 他にも送るものがある場合  */
    {
        char       **values;
        HeapTuple    tuple;
        Datum        result;

        /*
         * スロット内のストレージ用に values 配列を準備。
         * これは、後で適切な "in" 関数で処理される
         * C 文字列の配列でなければなりません。
         */
        values = (char **) palloc(3 * sizeof(char *));
        values[0] = (char *) palloc(16 * sizeof(char));
        values[1] = (char *) palloc(16 * sizeof(char));
        values[2] = (char *) palloc(16 * sizeof(char));

        snprintf(values[0], 16, "%d", 1 * PG_GETARG_INT32(1));
        snprintf(values[1], 16, "%d", 2 * PG_GETARG_INT32(1));
        snprintf(values[2], 16, "%d", 3 * PG_GETARG_INT32(1));

        /* タプルの作成 */
        tuple = BuildTupleFromCStrings(attinmeta, values);

        /* タプルを datum に変換 */
        result = TupleGetDatum(slot, tuple);

        /* クリーンアップ (これは必須ではありません) */
        pfree(values[0]);
        pfree(values[1]);
        pfree(values[2]);
        pfree(values);

         SRF_RETURN_NEXT(funcctx, result);
    }
    else    /* 何も残っていない場合 */
    {
         SRF_RETURN_DONE(funcctx);
    }
}

CREATE TYPE __testpassbyval AS (f1 int4, f2 int4, f3 int4);

CREATE OR REPLACE FUNCTION testpassbyval(int4, int4) RETURNS setof __testpassbyval
  AS 'MODULE_PATHNAME','testpassbyval' LANGUAGE 'c' IMMUTABLE STRICT;

9.5.7. コードの作成

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

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

• pg_config --includedir-server を使用して、使用中のシステム(もしくはユーザが実行するシステム)にてPostgreSQL サーバのヘッダファイルがインストールされた場所を見つけます。 このオプションは、PostgreSQL 7.2 で新しく導入された機能です。 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 9.5.8を参照してください。

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

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 9.5.1 を見直してください。