PostgreSQL 8.3.3문서
Prev Fast Backward Chapter 33. SQL 확장 Fast Forward Next

33.9. C언어 함수

사용자 정의의 함수는 C(혹은 C++와 같은 C와 호환성이 있는 언어)로 작성할 수가 있습니다. 그러한 함수는 동적 로드 가능 오브젝트(공유 라이브러리라고도 불립니다)로서 컴파일 되어 필요에 따라서 서버에 로드 됩니다. 동적 로드 기능이, "C언어"함수를 "내부"함수와 구별하는 것입니다. 코딩 방법은 기본적으로 양쪽 모두 같습니다 (따라, 표준 내부 함수 라이브러리는, 사용자 정의의 C함수의 코딩 예의 풍부한 정보원이 됩니다).

현재, 두 가지의 다른 호출 규약이 C함수로 사용되고 있습니다. 보다 새로운 "Version-1"호출 규약은, 이하에 나타내듯이, 그 함수용으로 호출 매크로PG_FUNCTION_INFO_V1()를 쓰는 것으로 나타납니다. 이 매크로가 존재하지 않으면, 구형식("Version-0")의 함수인 것을 나타냅니다. 어느 쪽의 경우도 CREATE FUNCTION로 지정하는 언어명은 C입니다. 구형식의 함수는, 이식성의 문제와 기능의 부족때문에 권유받지 않습니다. 이것은 현재, 호환성의 이유 때문에 존재하고 있습니다.

33.9.1. 동적 로딩

특정의 로드 가능 객체 내의 사용자 정의의 함수가 세션으로 최초로 불려 가면, 동적 로더는, 그 함수를 호출할 수 있도록, 객체 파일을 메모리내에 읽어들입니다. 그 때문에, 사용자 정의 C함수용의 CREATE FUNCTION는 그 함수에 대해, 로드 가능 객체 파일의 이름과, 객체 파일이 불려 가는 특정의 함수의 C명칭(링크 심볼)이라는 2개의 정보를 지정해야합니다. C명칭이 명시적으로 지정되지 않았던 경우, SQL에서의 함수명과 같은 것과 가정됩니다.

CREATE FUNCTION명령으로 주어진 이름에 근거해, 공유 객체 파일의 장소를 찾아낼 때에 이하의 알고리즘이 사용됩니다.

  1. 이름이 절대 패스의 경우, 지정된 파일이 읽힙니다.

  2. 이름이 $libdir라고 하는 문자열로 시작되는 경우, 그 부분은 PostgreSQL패키지의 라이브러리 디렉토리에서 옮겨놓을 수 있습니다. 이 디렉토리는 구축 시 결정됩니다.

  3. 이름에 디렉토리 부분이 없는 경우, 그 파일은 dynamic_library_path설정 변수로 지정된 패스내로부터 검색됩니다.

  4. 상기 이외의 경우(파일이 패스내에 존재하지 않는 경우나 상대 디렉토리 부분을 가지는 경우), 동적 로더는 지정된 이름을 그대로 사용해, 대부분의 경우는 실패합니다 (이것은 현재의 작업 디렉토리에 의존하기 위해 신뢰할 수 없습니다).

여기까지의 흐름이 잘 되지 않았던 경우, 플랫폼 독자적인 공유 라이브러리 파일 확장자(extension)(많은 경우. so)가 지정된 이름에 추가되어 재차 이 흐름을 시도합니다. 또 실패했을 경우, 로드가 실패합니다.

공유 라이브러리를 $libdir로부터 상대적으로, 혹은 동적 라이브러리 패스가 다닌 곳에 배치하는 것을 추천 합니다. 다른 장소에 새로운 설치를 배치하는 경우에 버전 업을 간단하게 합니다. $libdir가 가리키는 실제의 디렉토리는 pg_config --pkglibdir명령을 사용하는 것으로 합니다.

PostgreSQL서버의 실효 사용자 ID는 로드 예정의 파일의 패스까지 도달할 수 있어야 합니다. postgres사용자에 의해 읽을 수 있고, 실행가능한 파일 뿐만 아니라 상위 디렉토리를만들지 못하는 것이 자주 있는 실수입니다.

어느 경우에서도, CREATE FUNCTION명령에게 준 파일명은 그대로 시스템 카탈로그에 보존됩니다. 그러므로, 만약 그 파일을 재차 읽어들일 필요가 있는 경우, 같은 처리가 적용됩니다.

Note: PostgreSQL는 C함수를 자동적으로 컴파일 하지 않습니다. CREATE FUNCTION명령으로 참조하기 전에, 그 객체 파일은 컴파일되어 있지 않으면 안됩니다. 새로운 정보에 대해서는, Section 33.9.6을 참조해 주세요.

동적으로 로드된 객체 파일이 호환성이 없는 서버에 로드되지 않게 하기 위해, PostgreSQL는, 그 파일에 적절한 내용을 가지는 "마법의 블록"이 포함되어 있는지 검사합니다. 메이저 버젼이 다른 PostgreSQL용으로 컴파일 된 모듈 등과 같이, 서버가 눈에 띄게 호환성이 없는 것을 감지하게 해줍니다. 마법의 블록은 PostgreSQL 8.2로부터 요구되고 있습니다. 마법의 블록을 포함시키려면,이하를 모듈의 소스 파일에 한 번(한 번만), fmgr.h헤더 파일을 포함시킨 다음에, 기술해 주세요. 

#ifdef PG_MODULE_MAGIC
PG_MODULE_MAGIC;
#endif

그 코드를 릴리스 8.2보다 이전의 PostgreSQL용으로 컴파일 할 필요가 없으면, #ifdef테스트를 생략 할 수 있습니다.

최초로 사용된 후에, 동적으로 로드 된 객체는 메모리 내에 보관 유지됩니다. 동일 세션에 대해 그 파일 내의 함수를 향후에 호출했을 경우, 심볼 테이블 검색에 필요한 작은 오버헤드 밖에 걸리지 않습니다. 예를 들면 재컴파일 한 후 처럼, 그 객체 파일을 강제적으로 재차 로드하게 할 필요가 있는 경우는, LOAD 명령을 사용하거나 새로운 세션을 시작해 주세요.

생략 할 수도 있습니다만, 동적으로 로드 되는 파일에, 초기화 처리 함수와 최종 처리 함수를 포함할 수가 있습니다. _PG_init라고 하는 함수가 파일에 존재하면, 이 함수는 파일이 로드 된 직후에 불려 갑니다. _PG_fini라고 하는 함수가 파일에 존재하면, 이 함수는 파일이 언로드되기 직전에 불려 갑니다. 또, 이 함수는 인자를 취하지 않고 빈 값을 돌려주지 않으면 안됩니다. _PG_fini가 파일의 언로드시에만 불려 가는 것으로, 처리의 종료시에 불려 가는 것이 아닌 것에 주의해 주세요. (현재, 언로드는 명시적인 LOAD명령에 의한 파일 재로드의 문맥에서만 발생합니다. )

33.9.2. C언어 함수의 기본형

C언어 함수의 작성 방법을 이해하기 위해서는, PostgreSQL가 기본 데이터형을 내부에서 어떻게 표현해, 어떻게 그것들을 함수로 교환하고 있는지를 이해할 필요가 있습니다. 내부적으로 PostgreSQL는 기본형을 "메모리의 작은 덩어리"로 간주합니다. 어떠한 형태를 정의하는 사용자 정의 함수는, 바꾸어 말하면, PostgreSQL가 그것을 조작할 수 있는 방법을 정의합니다. 즉, PostgreSQL는 데이터의 저장, 디스크로부터의 취득만을 실시해, 데이터의 입력이나 처리, 출력에는 사용자 정의 함수를 사용합니다.

기본형은 아래와 같은 세 가지 중 하나의 내부 서식을 사용하고 있습니다.

값인도는, 1, 2, 4바이트 길이의 형태만이 사용 가능합니다(사용하는 머신의 sizeof(Datum)가 8의 경우는 8바이트나 가능합니다). 데이터형을 정의할 때, 그 형태가 모든 아키텍쳐에 대해 동일한 크기(바이트수)가 되도록 정의하도록 주의해 주세요. 예를 들면, long형은 머신에 따라서는 4바이트나 8바이트이기 때문에 위험하지만, int형은 대부분의 Unix 머신에서는 4바이트입니다. Unix 머신에 있어서의 int4의 이론적인 구현은 이하와 같이 됩니다. 

/* 4-byte integer, passed by value */
typedef int int4;

한편, 임의의 크기의 고정 길이의 형태는 참조로서 인도하는 것이 가능합니다. 예로서 이하에 PostgreSQL의 형태의 구현 샘플을 나타냅니다. 

/* 16 바이트 구조체, 참조 인도 */
typedef struct
{
    double  x, y;
} Point;

그러한 형태의 포인터만이 PostgreSQL함수의 입출력시에 사용할 수 있습니다. 그러한 형태의 값을 돌려주기 위해서는, palloc()를 사용해 올바른 크기의 메모리 영역을 할당해 그 메모리 영역에 값을 입력해, 그것의 포인터를 돌려줍니다 (또, 입력 인자의 하나와 같은 형태의 같은 값을 돌려주고 싶은 것이면, palloc를 실시하는 수고를 생략할 수가 있습니다. 이 경우는 입력값에 포인터를 단지 돌려주세요).

마지막으로, 모든 가변 길이형은 참조로서 인도할 필요가 있습니다. 또, 모든 가변 길이형은 정확하게 4바이트의 length 필드로부터 시작될 필요가 있어, 그 형태에 저장되는 모든 데이터는 length 필드의 바로 후의 메모리 영역에 놓여질 필요가 있습니다. length 필드에는 그 구조의 총 길이가 저장됩니다. 즉, length 필드 그 자체도 그 크기에 포함됩니다.

Warning

참조 인도의 입력값의 내용을 결코 변경하지 말아 주세요. 지정한 포인터가 디스크 버퍼를 직접 지시하고 있을 가능성이 자주 있기 때문에, 변경하면 디스크상의 데이터를 파괴해 버릴지도 모릅니다. 이 규칙의 유일한 예외에 대해 Section 33.10로 설명합니다.

예를 들면, text형을 정의하려면, 아래와 같이 실시할 수 있습니다. 

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

여기서 선언된 데이터 필드는, 분명하게 모든 취할 수 있는 문자열을 보관 유지할 수 있는 길이가 아닙니다. C언어에서는 가변 길이의 구조를 정의하는 것은 불가능하므로, C컴파일러는 배열의 첨자의 범위 검사를 실시하지 않는다는 사실에 의존합니다. 필요한 영역량을 할당해 마치 올바른 길이로 선언된 것 같이, 배열로서 접근 할 뿐입니다 (이 수법은 자주 사용됩니다. 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매크로를 사용하는 편이 바람직한 형식으로 간주해지고 있습니다.

Table 33-1는, PostgreSQL의 내장형을 사용하는 C언어 함수를 작성할 때의, C의 형태와 SQL형과의 대응을 지정한 것입니다. "정의 장소"열에서는, 형태 정의를 꺼내기 위해서 포함해야 하는 헤더 파일을 나타내고 있습니다 (실제의 정의는 파일에 열람된 것과는 다를 가능성이 있습니다. 사용자가 정의된 인터페이스를 엄수하는 것을 추천되고 있습니다). postgres.h에는 반드시 필요한 많은 것이 선언되고 있기 때문에, 반드시 처음에 소스 파일에 이 파일을 포함해야 하는 것에 주의해 주세요.

Table 33-1. 내장형 SQL형에 상응하는 C의 형태

SQL형 C 언어형 정의 장소
abstime AbsoluteTime utils/nabstime.h
boolean bool postgres.h(컴파일러로 짜넣어 끝난 가능성이 있습니다)
box BOX* utils/geo_decls.h
bytea bytea* postgres.h
"char" char (컴파일러로 내장이 끝난 상태)
character BpChar* postgres.h
cid CommandId postgres.h
date DateADT utils/date.h
smallint (int2) int2 or int16 postgres.h
int2vector int2vector* postgres.h
integer (int4) int4 or int32 postgres.h
real (float4) float4* postgres.h
double precision (float8) float8* postgres.h
interval Interval* utils/timestamp.h
lseg LSEG* utils/geo_decls.h
name Name postgres.h
oid Oid postgres.h
oidvector oidvector* postgres.h
path PATH* utils/geo_decls.h
point POINT* utils/geo_decls.h
regproc regproc postgres.h
reltime RelativeTime utils/nabstime.h
text text* postgres.h
tid ItemPointer storage/itemptr.h
time TimeADT utils/date.h
time with time zone TimeTzADT utils/date.h
timestamp Timestamp* utils/timestamp.h
tinterval TimeInterval utils/nabstime.h
varchar VarChar* postgres.h
xid TransactionId postgres.h

여기까지 기본형에 관해서 있을 수 있는 구조의 모두를 기술했으므로, 실제의 함수의 예를 몇 개 가리킬 수가 있습니다.

33.9.3. 버전 0 호출 규약

현재는 비추천하지만 이해하기 쉽기 때문에, 최초로 "오래된 스타일"의 호출 규약을 기술합니다. 버전-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(integer) RETURNS integer
     AS '
DIRECTORY
/funcs', 'add_one'
     LANGUAGE C STRICT;

-- "add_one"이라고 하는 SQL 함수명을 오버로드하고 있는 것에 주의
CREATE FUNCTION add_one(double precision) RETURNS double precision
     AS '
DIRECTORY
/funcs', 'add_one_float8'
     LANGUAGE C STRICT;

CREATE FUNCTION makepoint(point, point) RETURNS point
     AS '
DIRECTORY
/funcs', 'makepoint'
     LANGUAGE C STRICT;
                         
CREATE FUNCTION copytext(text) RETURNS text
     AS '
DIRECTORY
/funcs', 'copytext'
     LANGUAGE C STRICT;

CREATE FUNCTION concat_text(text, text) RETURNS text
     AS '
DIRECTORY
/funcs', 'concat_text'
     LANGUAGE C STRICT;

여기서, DIRECTORY 는 공유 파일의 디렉토리 (예를 들면, 본절로 사용하는 예의 코드가 포함되는 PostgreSQL튜토리얼 디렉토리)를 나타냅니다 (AS구중에서는 단지 'funcs'를 사용해, 다음에 DIRECTORY 를 검색 경로에 추가하는 편이 보다 좋은 방법입니다. 어느 경우에서도, 일반적으로 . so나 . sl가 사용되는, 공유 라이브러리용의 시스템 독특한 확장자(extension)를 생략 할 수가 있습니다).

여기서, 함수를 "엄밀(strict)"하게 지정하고 있는 것에 주목해 주세요. 이것은, 만약 입력된 값이 NULL였을 경우에, 시스템이 자동적으로 돌아가 결과도 NULL이라고 간주하는 것을 의미합니다. 이것을 실시하는 것에 의해, 함수의 코드에 입력값이 NULL값인지 체크를 할 필요가 없어집니다. 이것이 없으면, 각 참조 인도 인자의 NULL 포인터에 대한 체크를 실시하는 등, NULL값의 명시적인 체크를 실시할 필요가 있어 집니다. (값인도 인자에 관해서, 체크를 실시하는 방법은 존재하지 않습니다).

이러한 호출 규약은 용이합니다만, 이 방법은, 이식성의 면에서 그다지 우수하지 않습니다. int형의 것보다 작은 데이터형을 인도하는 부분에서 문제를 떠안고 있는 아키텍쳐도 존재합니다. 또, 함수의 결과로서 NULL를 돌려주는 간단한 방법은 없습니다. 게다가, 인자로서 NULL를 처리하는 방법으로서는, 함수를 엄밀한 것으로 하는 이외 방법은 없습니다. 다음에 설명하는 Version-1 규약에서는 이러한 문제가 해결되고 있습니다.

33.9.4. 버전 1 호출 규약

버전-1 호출 규약에서는, 인자와 결과의 인도의 복잡성을 없애기 위해서 매크로를 사용하고 있습니다. 버전-1함수의 C언어 선언은 반드시 아래와 같이 실시합니다. 

Datum funcname(PG_FUNCTION_ARGS)

또한, 매크로 호출 

PG_FUNCTION_INFO_V1(funcname);

는, 같은 소스 파일에 쓰여져 있어야 합니다 (일반적으로는, 함수의 바로 앞에 쓰여집니다). PostgreSQL에서는 모든 내부 함수는 버전-1이라고 인식하므로, 이 매크로의 호출은 internal언어 함수에서는 필요 없습니다. 그러나, 동적으로 로드 되는 함수에서는 필요합니다.

버전-1함수에서는, 각각의 열매 인자는, 인자의 데이터형에 맞는 PG_GETARG_ xxx ()매크로를 사용해 나돈 결과는 반환값의 형태에 맞는 PG_RETURN_ xxx ()매크로를 사용해 돌려주어집니다. PG_GETARG_ xxx ()는, 그 인자로서 꺼내는 함수 인자의 번호를 취합니다. PG_RETURN_ xxx ()는, 그 인자로서 실제로 돌려주는 값을 받습니다.

상기와 같은 함수를 버전-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용의 매크로는 참조 인도라는 성질을 숨깁니다 */

    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명령은, 버전-0과 같은 것입니다.

언뜻 보기에, 버전-1의 코딩 규약은 무의미한 것으로 보일지도 모릅니다. 그러나, 매크로가 필요없는 정보를 은폐하고 있으므로, 다수의 개선을 하고 있습니다. 예를 들면, add_one_float8의 코드에서는, float8가 참조 인도인 것을 의식할 필요가 없어졌습니다. 또 다른 예로서는, 가변 길이형의 GETARG매크로는 "TOAST 된"값(압축, 또는 행외)이 취급하는 필요성을 은폐 합니다.

버전-1함수의 하나의 큰 개선점은, NULL의 입력/결과의 처리 능력입니다. PG_ARGISNULL( n )매크로에 의해 함수는 각 입력이 NULL인지 아닌지 테스트를 실시할 수가 있습니다 (물론 이것은, "엄밀"히 선언되어 있지 않은 함수에서만 필요합니다). PG_GETARG_ xxx ()매크로에서는, 입력된 인자는 시작되어 값을 0으로서 열거할 수 있습니다. 인자가 NULL가 아닌 것을 확인할 때까지는, PG_GETARG_ xxx ()의 실행은 삼가해야 합니다. 결과적으로 NULL를 돌려주는 경우는, PG_RETURN_NULL()를 실행합니다. 이것은, 엄밀한 함수와 엄밀하지 않은 함수의 양쪽 모두로 사용 가능합니다.

새로운 형식의 인터페이스에서는, 그 외의 옵션으로서 PG_GETARG_ xxx ()매크로의 변형을 2개 제공하고 있습니다. 첫번째 PG_GETARG_ xxx _COPY()에 의해, 안전하게 기입할 수가 있는 지정 인자의 복사가 확실히 돌아옵니다 (통상의 매크로는, 물리적으로 테이블에 저장되고 있는 값에의 포인터를 돌려주는 일이 있으므로, 기입되지 않습니다. PG_GETARG_ xxx _COPY()매크로를 사용하는 것으로 안심해 결과에 기입할 수가 있습니다). 두번째 변형은, 인자를 3개 취하는 PG_GETARG_ xxx _SLICE()매크로로부터 됩니다. 첫번째는 함수의 인자의 수(상기대로)입니다. 두번째와 세번째는, 오프셋(offset)과 돌려주어지는 세그먼트(segment)의 길이입니다. 오프셋(offset)은 제로로부터 시작되고, 부의 길이는 나머지의 값을 돌려주는 것을 요구합니다. 이러한 매크로를 사용하면, 스토리지의 형태가 "external"(외부)인 큰 값의 일부에 접근 할 때에 매우 효과적입니다 (열의 스토리지의 형태는 ALTER TABLE tablename ALTER COLUMN colname SET STORAGE storagetype 를 사용해 지정할 수 있습니다. 스토리지의 형태는, plain, external, extended, 또는 main 중에 있습니다).

마지막으로, 버전-1함수 호출 규약에서는, 결과 집합(Section 33.9.10)을 돌려주는 것, 및 트리거 함수(Chapter 34)와 수속형 언어의 호출 핸들러(Chapter 47)를 구현할 수가 있습니다. 또, 버전-1 코드는, 표준 C의 함수 호출 프로토콜의 제약을 지키기 때문에, 버전-0보다 이식성이 있습니다. 자세한 것은 소스 배포물 내의 src/backend/utils/fmgr/README를 참조해 주세요.

33.9.5. 코드의 작성

보다 발전된 화제에 들어가기 전에, PostgreSQL C언어 함수의 코딩에 대한 규칙을 몇 개 설명합니다. C언어 이외의 언어로 기술한 함수를 PostgreSQL에 내장하는 것은 가능합니다만, 예를 들면 C++, FORTRAN나 Pascal라고 하는 언어는 C언어와 같은 호출과 규약에 따르지 않으므로, 많은 경우, (가능했다고 해도)곤란합니다. 그것은 즉, 다른 언어에서는 같은 방법으로 함수에 인자를 건네주거나 함수로부터 결과를 돌려주는 것을 실시하지 않는다는 것입니다. 이 때문에, C언어 함수는 실제로 C언어로 쓰여져 있는 것으로 가정합니다.

C함수의 작성과 구축의 기본 규칙을 이하에 나타냅니다.

33.9.6. 동적으로 로드 되는 함수의 컴파일과 링크

C로 작성된 PostgreSQL의 확장 함수를 사용하기 위해서는 서버에 의해 동적으로 로드될 수 있도록 특별한 방법을 통해 컴파일과 링크를 해야할 필요가 있습니다. 정확하게는공유 라이브러리를 만들 필요가 있습니다.

추가적인 정보는 operating system의 문서, 특히 C컴파일러, cc 그리고 링크 에디터, ld의 메뉴얼 페이지를 참조해 주십시요. 또한, PostgreSQL의 원시 코드는 contrib디렉토리 내에서 실례를 포함하고 있습니다. 그러나 이러한 예제에 의존을 하게 되면 PostgreSQL 원시코드의 유효성에 의존한 모듈이 만들지게 됩니다.

공유라이브러리를 생성하는 것은 일반적으로 실행 프로그램의 링크와 유사합니다. 우선 원시 파일이 오브젝트 파일에 컴파일 된 후 오브젝트 파일 간의 링크가 이루어집니다. 이러한 오브젝트 파일은 위치에 독립적인 코드(PIC)로서 만들어져야 합니다. 란 개념적으로는 실행프로그램에 의해 로드되어질 때 메모리 상의 임의의 장소에 위치되어질 수 있다는 것을 의미합니다. (실행 프로그램용으로 만들어진 오브젝트 파일은 이러한 방법으로 컴파일되지 않습니다.) 공유 라이브러리를 링크하는 명령문은 실행 프로그램의 링크와 구별되기 우한 특별한 플래그를 가집니다. (이론상으로 그러하며, 다른 시스템에서 실제 좀 더 추악하게 보여집니다.)

다음의 예를 통해 file foo.c 안에 원시 코드가 있다고 가정하고, foo.so 공유 라이브러리를 만들 것입니다. 중간의 오브젝트 파일은 특별한 언급이 없는 한 foo.o으로 불릴 것입니다. 공유 라이브러리는 한 개 이상의 오브젝트 파일을 가질 수 있으나, 여기에서는 한 가지만 사용하였습니다.

BSD/OS

PIC를 만들기 위한 컴파일러 플래그는 -fpic입니다. 공유 라이브러리를 생성하는 링크 플래그는-shared입니다. 

gcc -fpic -c foo.c
ld -shared -o foo.so foo.o

위는 버전 4.0에서 적용됩니다.

FreeBSD

PIC를 만들기 위한 컴파일러 플래그는-fpic입니다. 공유 라이브러리를 만드는 컴파일러 플래그는-shared입니다. 

gcc -fpic -c foo.c
gcc -shared -o foo.so foo.o

위는 FreeBSD의 버전 3.0에서 적용됩니다.

HP-UX

PIC를 만들기 위한 시스템 컴파일러의 컴파일러 플래그는+z입니다. GCC를 사용하는 경우는-fpic입니다. 공유 라이브러리를 위한 링크 플래그는-b입니다. 따라서, 이하와 같이 됩니다. 

cc +z -c foo.c

or 

gcc -fpic -c foo.c

그리고 

ld -b -o foo.sl foo.o

HP-UX는 대부분의 다른 시스템과 달리 공유 라이브러리에 . sl라고 하는 확장자(extension)를 사용합니다.

IRIX

PIC는 디폴트로 특별한 컴파일러 옵션은 필요하지 않습니다. 공유 라이브러리를 만들기 위한 링크 옵션은-shared입니다. 

cc -c foo.c
ld -shared -o foo.so foo.o

Linux

PIC를 만들기 위한 컴파일러 플래그는-fpic입니다. 몇가지 상황에서 몇몇의 플랫폼은 -fpic가 동작하지 않을 경우, -fPIC를 사용해야만 합니다. 보다 많은 정보를 원하시는 분은 GCC의 메뉴얼을 참조해 주십시요. 공유 라이브러리를 만들기 위한 컴파일러 플래그는-shared입니다. 완전한 예는 다음과 같습니다. 

cc -fpic -c foo.c
cc -shared -o foo.so foo.o

MacOS X

아래의 예는 개발자용 툴이 설치된 것을 전제로 하고 있습니다. 

cc -c foo.c 
cc -bundle -flat_namespace -undefined suppress -o foo.so foo.o

NetBSD

PIC를 만들기 위한 컴파일러 플래그는-fpic입니다. ELF시스템에서는 컴파일러가 -shared플래그를 사용해 공유 라이브러리를 링크합니다. 보다 오래된 non-ELF 시스템에서는 ld -Bshareable를 사용합니다. 

gcc -fpic -c foo.c
gcc -shared -o foo.so foo.o

OpenBSD

PIC를 만들기 위한 컴파일러 플래그는-fpic입니다. 공유 라이브러리에 링크하려면ld -Bshareable를 사용합니다. 

gcc -fpic -c foo.c
ld -Bshareable -o foo.so foo.o

Solaris

PIC를 만들기 위한 컴파일러 플래그는 Sun 컴파일러에서는-KPIC이고, GCC에서는-fpic입니다. 공유 라이브러리를 링크하기 위해서는, 두 컴파일러에서 컴파일러 옵션을 -G로 사용합니다. 대신 GCC의 경우에는 -shared옵션을 사용할 수 있습니다. 

cc -KPIC -c foo.c
cc -G -o foo.so foo.o

또는 

gcc -fpic -c foo.c
gcc -G -o foo.so foo.o

Tru64 UNIX

PIC는 디폴트로 컴파일 명령문은 일반적인 것입니다. 링크를 하기 위해서는 특별한 옵션을 가진 ld가 사용됩니다. 

cc -c foo.c
ld -shared -expect_unresolved '*' -o foo.so foo.o

시스템의 컴파일러를 대신해 GCC를 사용하는 경우도 같은 순서입니다. 특별한 옵션은 필요하지 않습니다.

UnixWare

PIC를 만들기 위한 컴파일러 플래그는 SCO 컴파일러에서는-KPIC가 사용되며, GCC에서는 -fpic입니다. 공유 라이브러리의 링크하기 위해서 SCO 컴파일러에서는 컴파일러 옵션으로 -G이 사용되고, GCC에서는-shared가 사용됩니다. 

cc -K PIC -c foo.c
cc -G -o foo.so foo.o

또는 

gcc -fpic -c foo.c
gcc -shared -o foo.so foo.o

Tip: 위의 내용이 복잡하여 이해가 어려울 경우, 동일한 인터페이스를 통해 플래폼의 차이를 감춰주는 GNU Libtool 의 사용을 고려해 보십시요.

완성된 공유 라이브러리 파일은PostgreSQL에 로드할 수 있습니다. CREATE FUNCTION 명령문으로 파일명을 지정할 때에는, 중간 오브젝트 파일이 아닌 공유 라이브러리 파일명의 이름을 주십시요. 시스템의 표준 공유 라이브러리용의 확장자(extension)(통상. so혹은. sl)는 CREATE FUNCTION으로 생략이 가능하며, 일반적으로 이식성을 가장 높이기 위한 방법으로 생략되어집니다.

서버가 라이브러리 파일을 어디에 찾아낼까에 관해 Section 33.9.1을 다시 참조하여 주십시요.

33.9.7. 확장 구축 기반

PostgreSQL확장 모듈의 배포를 예정하고 있는 경우, 구축 시스템을 이식 가능하게 하기 위한 설정은 꽤 곤란합니다. 그 때문에, PostgreSQL의 설치에서는, 단순한 확장 모듈을 설치가 끝난 서버에 간단하게 구축할 수 있도록 PGXS라는 확장용의 구축 기반을 제공하고 있습니다. 이 기반은, PostgreSQL와 교환하는 모든 소프트웨어를 구축하기 위해서 사용할 수 있는 것 같은 종합적인 구축 시스템 체제를 목적으로 한 것은 아닌 것에 주의해 주세요. 이것은 단지 단순한 서버 확장 모듈로 공통되는 구축 순서를 자동화하는 것입니다. 좀 더 복잡한 패키지에서는, 독자적으로 구축 시스템을 작성할 필요가 있습니다.

독자적인 확장 모듈용으로 이 기반을 사용하려면, 간단한 Makefile를 작성하지 않으면 안됩니다. 이 Makefile로, 몇 개의 변수를 설정해, 마지막에 PGXS전체의 Makefile를 포함시켜야합니다. 여기에서는, isbn_issn라는 이름의 확장 모듈을 구축하기 위한 예를 나타냅니다. 이 모듈은 공유 라이브러리, SQL 스크립트, 및 문서용의 텍스트 파일로부터 구성되어 있습니다. 

MODULES = isbn_issn
DATA_built = isbn_issn.sql
DOCS = README.isbn_issn

PGXS := $(shell pg_config --pgxs)
include $(PGXS)

마지막 3행은 항상 같을 것입니다. 그 전에, 변수의 대입이나 독자적인 make규칙의 추가를 실시합니다.

이하의 변수를 설정할 수 있습니다.

MODULES

같은 계통의 소스 파일로부터 구축되는 공유 객체의 리스트입니다 (이 리스트에는 확장자(extension)를 포함하지 말아 주세요).

DATA

prefix /share/contrib에 설치되는 여러가지 파일입니다.

DATA_built

최초로 구축되지 않으면 안 되는 prefix /share/contrib에 설치되는 여러가지 파일입니다.

DOCS

prefix /doc/contrib에 설치되는 여러가지 파일입니다.

SCRIPTS

prefix /bin에 설치 되는(바이너리가 아닌) 스크립트 파일입니다.

SCRIPTS_built

최초로 구축되지 않으면 안 되는, prefix /bin에 설치되는(바이너리가 아닌) 스크립트 파일입니다.

REGRESS

리그렛션테스트케이스의(확장자(extension) 없음의) 리스트입니다. 후술 합니다.

혹은, 이하의 2개 가운데, 대부분 1개입니다.

PROGRAM

(OBJS의 객체 파일의 리스트로부터) 구축되는 바이너리 프로그램입니다.

MODULE_big

(OBJS의 객체 파일의 리스트로부터) 구축되는 공유 객체입니다.

이하의 변수도 설정할 수가 있습니다.

EXTRA_CLEAN

make clean로 삭제되는 불필요한 파일입니다.

PG_CPPFLAGS

이것은 CPPFLAGS에 추가됩니다.

PG_LIBS

이것은 PROGRAM의 링크행에 추가됩니다.

SHLIB_LINK

이것은 MODULE_big의 링크행에 추가됩니다.

이 Makefile를 확장 모듈을 저장하는 디렉토리에 Makefile로서 보존해 주세요. 그 후, make로 독자 모듈의 컴파일을, make install로 독자 모듈의 설치를 실시할 수가 있습니다. 디폴트로 확장 모듈은, 검색 경로내에서 최초로 발견되는 pg_config명령에 대응하는 PostgreSQL설치 전용으로 컴파일 되어 설치됩니다. Makefile내 또는 make의 명령 라인상에서 PG_CONFIG를 다른 설치의 pg_config프로그램을 지시하도록 변경하는 것으로 다른 설치를 사용할 수가 있습니다.

PostgreSQL 주서버로 사용되는 make installcheck 멈춘 구 같이 REGRESS변수내에 열거된 스크립트가 독자적인 모듈의 리그렛션테스트용으로 사용됩니다. 이것이 동작하기 위해서는, 독자 확장의 디렉토리내에 sql/라는 명칭의 디렉토리를 준비해, 그 중에 실행시키고 싶은 시험 그룹 각각 1개의 파일을 저장해야 합니다. 이 파일의 확장자(extension)는 . sql가 아니면 안됩니다. 또, makefile 파일내의 REGRESS리스트에는 이 확장자(extension)를 포함해서는 안됩니다. 각각의 시험에 관해서, expected/라는 명칭의 디렉토리에, . out라는 확장자(extension)로 상정 결과를 파일로서 저장합니다. 시험은 make installcheck에 의해 실행되어 그 결과는 상정치 파일이라고 비교됩니다. 차이점은 diff -c의 서식에서 regression.diffs라고 하는 파일에 써내집니다. 상정치 파일이 존재하지 않는 시험을 실행하면 "장애"로서 보고되기 때문에, 상정치 파일이 모두 존재하는지 확인해 주세요.

Tip: 상정치 파일의 가장 간단한 작성 방법은 빈 파일을 작성해, 시험을 실행한 후의 결과 파일(results/디렉토리에 있습니다.)을, 그것이 정말로 시험 결과적으로 올바른 것인지 주의 깊게 검사한 후에 expected/에 복사하는 것입니다.

33.9.8. 복합형 인자

복합형에서는 C의 구조와 같은 고정의 레이아웃이 없습니다. 복합형의 인스턴스는 NULL 필드를 가질 수가 있습니다. 게다가 복합형으로 계승 계층의 일부인 것은, 같은 계승 계층의 다른 멤버와는 다른 필드를 가질 수도 있습니다. 그 때문에, PostgreSQL는 C언어로부터 복합형의 필드에 접근하기 위한 함수 인터페이스를 제공합니다.

이하와 같이 쿼리에 대답하는 함수를 쓰려고 한다고 가정합니다. 

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

버전-0 호출 규약을 사용하면, c_overpaid는 이하와 같이 정의할 수 있습니다. 

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

bool
c_overpaid(HeapTupleHeader t, /* emp의 현재의 행 */
           int32 limit)
{
    bool isnull;
    int32 salary;

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

버전-1으로 작성하면, 위의 함수는 이하와 같이 됩니다. 

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

PG_FUNCTION_INFO_V1(c_overpaid);

Datum
c_overpaid(PG_FUNCTION_ARGS)
{
    HeapTupleHeader  t = PG_GETARG_HEAPTUPLEHEADER(0);
    int32            limit = PG_GETARG_INT32(1);
    bool isnull;
    Datum salary;

    salary = GetAttributeByName(t, "salary", &isnull);
    if (isnull)
        PG_RETURN_BOOL(false);
    /* 이 외, salary가 NULL의 경우에는 PG_RETURN_NULL()를 실시하는 것이 좋을 것입니다 */

    PG_RETURN_BOOL(DatumGetInt32(salary) > limit);
}

GetAttributeByName는, 지정된 행으로부터 속성을 돌려주는, PostgreSQL시스템 함수입니다. 이것에는 3개의 인자가 있습니다. 그것들은, 함수에게 건네진 HeapTupleHeader형의 인자, 요구된 속성의 이름, 속성이 NULL인지 아닌지를 통지하는 매개변수입니다. GetAttributeByName는 적절한 DatumGet XXX ()매크로를 사용해 적절한 데이터형에 변환 가능한 Datum형의 값을 돌려줍니다. 이 NULL 플래그가 설정되어 있는 경우, 반환값의 의미가 없는 것에 주의해, 이 결과로 무엇인가를 실시하려고 하기 전에 항상, NULL 플래그를 검사해 주세요.

목표열을 이름은 아니고 열번호로 선택하는 GetAttributeByNum도 있습니다.

아래와 같은 명령으로 c_overpaid함수를 SQL로 선언합니다. 

CREATE FUNCTION c_overpaid(emp, integer) RETURNS boolean
    AS '
DIRECTORY
/funcs', 'c_overpaid'
    LANGUAGE C STRICT;

입력 인자가 NULL인지 아닌지를 검사할 필요가 없게 STRICT를 사용하고 있는 것에 주의해 주세요.

33.9.9. 행(복합형)을 돌려준다

C언어 함수로부터 행 혹은 복합형의 값을 돌려주기 위해서, 복합형의 복잡한 작성의 대부분을 은폐 하는 매크로나 함수를 제공하는, 특별한 API를 사용할 수가 있습니다. 이 API를 사용하기 위해서는, 소스 파일로 이하를 포함할 필요가 있습니다. 

#include "funcapi.h"

복합형의 데이터값(이후 "튜플" 적는다)를 작성하는 2개의 방법이 있습니다. Datum값의 배열로부터 작성하는 방법, 혹은 튜플이 있는 열의 형태의 입력 변환 함수에 건네줄 수가 있는 C캐릭터 라인의 배열로부터 작성하는 것입니다. 어느 쪽의 방법에서도, 우선 튜플 구조 체용의 TupleDesc기술어를 입수, 혹은 작성하지 않으면 안됩니다. Datum를 사용하는 경우는, TupleDesc를 BlessTupleDesc에 건네주어, 각 행에 대해서 heap_form_tuple를 호출합니다. C문자열을 사용하는 경우는, TupleDesc를 TupleDescGetAttInMetadata에 건네주어, 각 행에 대해서 BuildTupleFromCStrings를 호출합니다. 튜플의 집합을 돌려주는 함수의 경우, 이 설정 단계를 최초의 함수 호출로 한 번에 정리해 실시할 수가 있습니다.

필요한 TupleDesc의 설정용의 보조용 함수가 몇 개 있습니다. 대부분의 복합형을 돌려주는 함수에서의 추천 방법은, 이하의 함수를 호출해, 호출 원래의 함수 자신에게 건네지는 fcinfo구조와 같은 것을 건네주는 것입니다. 

TypeFuncClass get_call_result_type(FunctionCallInfo fcinfo,
                                   Oid *resultTypeId,
                                   TupleDesc *resultTupleDesc)

(이것에는 물론, 버전 1 호출 규약을 사용하고 있는 것이 필요합니다). resultTypeId를 NULL로 하는 일도, 로컬 변수의 주소를 지정해 함수의 반환값형을 받을 수가 있습니다. resultTupleDesc는 로컬인 TupleDesc변수의 주소가 아니면 안됩니다. 결과가TYPEFUNC_COMPOSITE화도인지를 확인해 주세요. TYPEFUNC_COMPOSITE였을 경우, resultTupleDesc에는 필요한 TupleDesc가 저장되고 있습니다. (TYPEFUNC_COMPOSITE는 아니었던 경우, "레코드형을 받아들이지 않는 문맥으로 레코드를 돌려주는 함수가 불려 갔던 "이라고 하는 에러를 보고할 수가 있습니다. )

Tip: get_call_result_type는, 다형 함수의 결과의 실제의 형태를 해결할 수가 있습니다. 그러므로, 복합형을 돌려주는 함수 만이 아니고, 스칼라의 다양 결과를 돌려주는 함수에서도 의미가 있습니다. resultTypeId출력은 주로 스칼라의 다양 결과를 돌려주는 함수로 의미가 있습니다.

Note: get_call_result_type는, get_expr_result_type와 닮은 것 같은 함수로, 함수 호출로 상정되는 출력형을 식의 트리 구조로서 해결합니다. 함수 자신 이외로부터 결과형을 결정하고 싶은 경우에, 이것을 사용할 수가 있습니다. 또, get_func_result_type라고 하는 함수도 있습니다. 이것은 함수의 OID를 이용할 수 있는 경우에게만 사용할 수가 있습니다. 그러나, 이러한 함수는, record형을 돌려주는 것이라고 선언된 함수에서는 사용할 수 없습니다. 또, get_func_result_type는 다형 형태을 해결할 수가 없습니다. 따라서, 우선해 get_call_result_type를 사용해야 합니다.

낡고, 폐지 예정의 TupleDesc를 입수하기 위한 함수를 이하에 나타냅니다. 

TupleDesc RelationNameGetTupleDesc(const char *relname)

이것을 지명한 릴레이션의 행형용의 TupleDesc를 꺼내기 위해서 사용해 주세요. 또, 

TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases)

이것을 형태의 OID에 근거해 TupleDesc를 꺼내기 위해서 사용해 주세요. 이것은 기본형, 혹은 복합형의 TupleDesc를 꺼내기 위해서 사용 가능합니다. 이것은 record를 돌려주는 함수에서는 잘 작동하지 않습니다. 또, 다형 형태을 해결할 수도 있습니다.

TupleDesc를 획득한 후에, Datum를 사용하는 경우는 이하를 호출해 주세요. 

TupleDesc BlessTupleDesc(TupleDesc tupdesc)

C캐릭터 라인을 사용하는 경우는 이하를 호출해 주세요. 

AttInMetadata *TupleDescGetAttInMetadata(TupleDesc tupdesc)

집합을 돌려주는 함수를 작성하는 경우는, 이러한 함수의 결과를 FuncCallContext구조에 저장해 주세요. 각각 tuple_desc와 attinmeta를 사용합니다.

Datum를 사용하는 경우는, 사용자 데이터를 Datum 형식에 저장한 HeapTuple를 구축하기 위해서 이하를 사용합니다. 

HeapTuple heap_form_tuple(TupleDesc tupdesc, Datum *values, bool *isnull)

C문자열을 사용하는 경우는, 사용자 데이터를 C문자열 형식에 저장한 HeapTuple를 구축하기 위해서 이하를 사용합니다. 

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

values하행의 각 속성을 1 요소로 한 C문자열의 배열입니다. 각 C문자열은, 속성의 데이터형용의 입력 함수가 받아들이고 가능한 형식이 아니면 안됩니다. 속성의 값을 NULL값으로서 돌려주기 위해서는, values배열의 대응하는 포인터에 NULL를 설정해 주세요. 이 함수는 돌려주는 행 각각 대해 반복해 호출할 필요가 있습니다.

함수로부터 돌려주는 튜플을 다 구축했으면, 그것을 Datum로 변환하지 않으면 안됩니다. 이하를 사용해, HeapTuple를 유효한 Datum로 변환해 주세요. 

HeapTupleGetDatum(HeapTuple tuple)

단일행만을 돌려준다면, 이 Datum를 직접 돌려줄 수가 있습니다. 아니면, 집합을 돌려주는 함수에 있어서의 현재의 반환값으로서 사용할 수가 있습니다.

다음 섹션에 예를 나타냅니다.

33.9.10. 집합을 돌려준다

C언어 함수로부터 집합(복수행)을 돌려주는 기능을 위해서 특수한 API가 준비되어 있습니다. 집합을 돌려주는 함수는, 버전-1 호출 규약에 따를 필요가 있습니다. 또, 소스 파일은 상술한 대로 funcapi.h를 포함 할 필요가 있습니다.

집합을 돌려주는 함수(SRF)는 돌려주어지는 항목 마다 불려 갑니다. 그 때문에, SRF는, 과거의 조작을 기억해 호출의 번에 다음의 항목을 돌려주기 위해서 충분한 상태를 유지하고 있을 필요가 있습니다. 이 처리를 제어를 보조하기 위한 FuncCallContext구조가 갖춰지고 있습니다. 함수내에서는, 복수의 호출에 걸치는 FuncCallContext에의 포인터를 보관 유지하려면, fcinfo->flinfo->fn_extra를 사용합니다. 

typedef struct
{
    /*
     * 이미 행해진 호출의 회수.
     * 
     * SRF_FIRSTCALL_INIT()에 의해 call_cntr가 0에 초기화되어
     * SRF_RETURN_NEXT()가 불려 갈 때에 증분 됩니다.
     */
    uint32 call_cntr;

    /*
     * 생략 가능 : 호출의 최대수
     *
     * max_calls는, 편의상 준비되어 있는 것만으로, 설정은 생략 가능합니다.
     * 설정되어 있지 않으면, 함수가 종료한 것을 알기 위한 다른 방법을
     * 준비할 필요가 있습니다.
     */
    uint32 max_calls;

    /*
     * 생략 가능 : 결과 슬롯에의 포인터
     * 
     * 이것은 폐지되어 후방 호환성, 즉 비추천의 TupleDescGetSlot()를 사용하고
     * 사용자 정의의 SRF를 위해서만 존재합니다.
     */
    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;

    /*
     * 생략 가능: 튜플 설명을 포함한 구조에의 포인터.
     * tuple_desc는 튜플(즉 복합 데이터형)을 돌려주는 경우에 사용되어 BuildTupleFromCStrings()
     * 보다는 heap_form_tuple()를 사용해 튜플을 작성하는 경우에게만 필요합니다.
     * 통상 여기에 저장되는 TupleDesc는 최초로 BlessTupleDesc()를 최초로 실행한 것이어야 합니다.
     * 선.
    */
    TupleDesc tuple_desc;

} FuncCallContext;

SRF는 몇 개의 함수 및 매크로를 사용해 FuncCallContext구조를 자동적으로 조작합니다 (또 fn_extra로 검색하는 것을 상정합니다). 

SRF_IS_FIRSTCALL()

를 사용해, 그 함수 호출이 첫 번째 것인지, 두번째 이후인지를 판단합니다. 최초의 호출(오직)로, 

SRF_FIRSTCALL_INIT()

을 사용해, FuncCallContext를 초기화합니다. 최초의 호출을 포함한 모든 호출로, 

SRF_PERCALL_SETUP()

를 사용해, FuncCallContext를 사용하기 위한 적절한 설정을 실시해, 이전의 경로로부터 남아 있는 결과 데이터를 소거합니다.

함수로 돌려주어야 할 데이터가 있는 경우는, 

SRF_RETURN_NEXT(funcctx, result)

를 사용해, 그 데이터를 호출해 측에 돌려줍니다 (먼저 설명한 대로 result는 Datum형, 즉 1개의 값 또는 튜플일 필요가 있습니다). 마지막으로, 함수가 데이터를 다 돌려주었으면, 

SRF_RETURN_DONE(funcctx)

를 사용해 SRF를 클린 업 해 종료합니다.

SRF의 호출시에 현행이 되어 있는 메모리 컨텍스트는 일시적인 문맥으로, 각 호출동안에 소거됩니다. 즉 palloc를 사용해 할당한 것의 모두를 pfree할 필요는 없습니다. 이것들은 머지않아 소거되는 것이기 때문입니다. 그러나, 데이터 구조를 복수의 호출에 건너 사용하도록 할당하는 경우는, 어딘가 다른 장소에 놓아둘 필요가 있습니다. multi_call_memory_ctx에 의해 참조되는 메모리 컨텍스트는, SRF의 실행이 끝날 때까지 사용 가능하게 해야 하는 데이터의 보관 장소로서 적합합니다. 즉, 대부분의 경우, 최초의 호출의 셋업중에 multi_call_memory_ctx에 바꿀 필요가 있다고 하는 것입니다.

완전한 유사 코드의 예를 나타냅니다. 

Datum
my_set_returning_function(PG_FUNCTION_ARGS)
{
    FuncCallContext  *funcctx;
    Datum             result;
    MemoryContext     oldcontext;
    
further declarations as needed


    if (SRF_IS_FIRSTCALL())
    {
        funcctx = SRF_FIRSTCALL_INIT();
        oldcontext = MemoryContextSwitchTo(funcctx->multi_call_memory_ctx);
        /* 한 번의 셋업 코드가 여기에 들어갑니다: */
        
user code

        
if returning composite

            
build TupleDesc, and perhaps AttInMetadata

        
endif returning composite

        
user code

        MemoryContextSwitchTo(oldcontext);
    }

    /* 매회 실행하는 셋업 코드가 여기에 들어갑니다: */
    
user code

    funcctx = SRF_PERCALL_SETUP();
    
user code


    /* 이것은, 종료했는지 아닌지를 테스트하는 방법의 하나입니다: */
    {
        /* 여기서, 다른 항목을 돌려줍니다: */
        
user code

        
obtain result Datum

        SRF_RETURN_NEXT(funcctx, result);
    }
    else
    {
        /* 이것으로 항목을 다 돌려주었습니다.  후는 클린 업 할 뿐입니다.  */
        
user code

        SRF_RETURN_DONE(funcctx);
    }
}

복합형을 돌려주는 단순한 SRF의 완전한 예는 이하와 같습니다. 

PG_FUNCTION_INFO_V1(retcomposite);

Datum
retcomposite(PG_FUNCTION_ARGS)
{
    FuncCallContext     *funcctx;
    int                  call_cntr;
    int                  max_calls;
    TupleDesc            tupdesc;
    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);

        /*  결과형용의 튜플 기술어를 작성 */
        if (get_call_result_type(fcinfo, NULL, &tupdesc) != TYPEFUNC_COMPOSITE)
            ereport(ERROR,
                    (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
                     errmsg("function returning record called in context "
                            "that cannot accept type record")));

        /*
         * 다음에 미가공의 C문자열으로부터 튜플을 작성하기 위해서 필요하다
         * 속성 메타데이터의 생성
         */
        attinmeta = TupleDescGetAttInMetadata(tupdesc);
        funcctx->attinmeta = attinmeta;

        MemoryContextSwitchTo(oldcontext);
    }

    /* 모든 함수 호출로 실행 */
    funcctx = SRF_PERCALL_SETUP();

    call_cntr = funcctx->call_cntr;
    max_calls = funcctx->max_calls;
    attinmeta = funcctx->attinmeta;
 
    if (call_cntr < max_calls)    /* 그 밖에도 보내는 것이 있는 경우  */
    {
        char       **values;
        HeapTuple    tuple;
        Datum        result;

        /*
         * 돌려주는 튜플을 구축하기 위한 값의 배열을 준비합니다.
         * 이것은, 다음에 적절한 입력 함수로 처리된다
         * 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 = HeapTupleGetDatum(tuple);

        /* 클린 업(이것은 필수가 아닙니다) */
        pfree(values[0]);
        pfree(values[1]);
        pfree(values[2]);
        pfree(values);

        SRF_RETURN_NEXT(funcctx, result);
    }
    else    /* 아무것도 남지 않은 경우 */
    {
        SRF_RETURN_DONE(funcctx);
    }
}

이하에 이 함수를 SQL로 선언하는 일례를 나타냅니다. 

CREATE TYPE __retcomposite AS (f1 integer, f2 integer, f3 integer);

CREATE OR REPLACE FUNCTION retcomposite(integer, integer)
    RETURNS SETOF __retcomposite
    AS '
filename
', 'retcomposite'
    LANGUAGE C IMMUTABLE STRICT;

그 밖에도 이하와 같이 OUT 매개변수를 사용하는 방법도 있습니다. 

CREATE OR REPLACE FUNCTION retcomposite(IN integer, IN integer,
    OUT f1 integer, OUT f2 integer, OUT f3 integer)
    RETURNS SETOF record
    AS '
filename
', 'retcomposite'
    LANGUAGE C IMMUTABLE STRICT;

이 방법에서는, 함수의 출력형은 형식상 익명의 record형이 되는 것에 주의해 주세요.

소스 배포물내의 contrib/tablefunc디렉토리에는, 집합을 돌려주는 함수보다 많은 예가 있습니다.

33.9.11. 인수와 반환값의 다향성

C언어 함수는, anyelement, anyarray, anynonarray 및 anyenum다향형을 받아들이거나, 또는 돌려주도록 선언할 수가 있습니다. 다향 함수의 상세한 설명은 Section 33.2.5을 참조해 주세요. 함수의 인자 혹은 반환값이 다향형으로서 정의될 때, 함수의 작성자는 미리 호출함에 있어서의 데이터형이나 돌려주어야 할 데이터형이 무엇인지 알 수 없습니다. 버전-1 C함수로 인자의 열매 데이터형과 돌려주어야 하는 것과 상정된 형태를 발견할 수 있기 위한 2개의 루틴이 fmgr.h에 준비되어 있습니다. 이 루틴은 get_fn_expr_rettype(FmgrInfo *flinfo)와 get_fn_expr_argtype(FmgrInfo *flinfo, int argnum)라는 이름입니다. 이것들은 결과 혹은 인자형의 OID를 돌려줍니다. 다만, 만약 정보를 이용할 수 없으면 InvalidOid를 돌려줍니다. flinfo구조는 통상 fcinfo->flinfo로서 접속 됩니다. argnum매개변수는 0으로부터 시작됩니다. 또, get_fn_expr_rettype 대신에 get_call_result_type를 사용할 수도 있습니다.

예를 들면, 임의의 형태의 단일 요소를 받아들여 그 형태의 1 차원 배열을 돌려주는 함수를 생각해 보겠습니다. 

PG_FUNCTION_INFO_V1(make_array);
Datum
make_array(PG_FUNCTION_ARGS)
{
    ArrayType  *result;
    Oid         element_type = get_fn_expr_argtype(fcinfo->flinfo, 0);
    Datum       element;
    bool        isnull;
    int16       typlen;
    bool        typbyval;
    char        typalign;
    int         ndims;
    int         dims[MAXDIM];
    int         lbs[MAXDIM];

    if (!OidIsValid(element_type))
        elog(ERROR, "could not determine data type of input");

 
    /* 주어진 요소가 NULL인지 아닌지 주의하면서, 요소를 꺼냅니다. */
   isnull = PG_ARGISNULL(0);
    if (isnull)
        element = (Datum) 0;
    else
        element = PG_GETARG_DATUM(0);

    /* 차원수는 1 */
    ndims = 1;
    /* 요소를 1개 */
    dims[0] = 1;
    /* 하한은 1 */
    lbs[0] = 1;

    /* 이 요소형에 관한 필요 정보를 꺼낸다.  */
   get_typlenbyvalalign(element_type, &typlen, &typbyval, &typalign);

    /* 여기서 배열을 작성 */
    result = construct_md_array(&element, &isnull, ndims, dims, lbs,
                                element_type, typlen, typbyval, typalign);

    PG_RETURN_ARRAYTYPE_P(result);
}

이하의 명령은 SQL로 make_array함수를 선언합니다. 

CREATE FUNCTION make_array(anyelement) RETURNS anyarray
    AS '
DIRECTORY
/funcs', 'make_array'
    LANGUAGE C IMMUTABLE;

33.9.12. 공유 메모리와 LWLocks

애드 인(Add In)는 LWLocks(경량 락)와 서버 기동시에 공유 메모리의 할당을 보관 유지할 수가 있습니다. shared_preload_libraries 로 지정해, 이러한 애드 인(Add In)의 공유 라이브러리를 사전에 로드하지 않으면 안됩니다. 공유 메모리는, 그 _PG_init함수로 이하를 호출하는 것으로 보관 유지됩니다. 

void RequestAddinShmemSpace(int size)

LWLocks는 그 _PG_init함수로 이하를 호출하는 것으로 보관 유지됩니다. 

void RequestAddinLWLocks(int n)

경합 상태의 가능성을 방지하기 위해서, 할당할 수 있었던 공유 메모리에의 접속이나 그 초기화시에, 이하와 같이 각 연구 최종 단계에 AddinShmemInitLock경량 락을 사용하지 않으면 안됩니다. 

        static mystruct *ptr = NULL;

        if (!ptr)
        {
                bool    found;

                LWLockAcquire(AddinShmemInitLock, LW_EXCLUSIVE);
                ptr = ShmemInitStruct("my struct name", size, &found);
                if (!ptr)
                        elog(ERROR, "out of shared memory");
                if (!found)
                {
                        initialize contents of shmem area;
                        acquire any requested LWLocks using:
                        ptr->mylockid = LWLockAssign();
                }
                LWLockRelease(AddinShmemInitLock);
        }

Prev Home Next
내부 함수 Up 사용자 정의의 집계