2002-06-20 22:39:04 +02:00
|
|
|
/*-------------------------------------------------------------------------
|
|
|
|
*
|
|
|
|
* funcapi.h
|
|
|
|
* Definitions for functions which return composite type and/or sets
|
|
|
|
*
|
|
|
|
* This file must be included by all Postgres modules that either define
|
|
|
|
* or call FUNCAPI-callable functions or macros.
|
|
|
|
*
|
|
|
|
*
|
|
|
|
* Copyright (c) 2002, PostgreSQL Global Development Group
|
|
|
|
*
|
|
|
|
*
|
|
|
|
*-------------------------------------------------------------------------
|
|
|
|
*/
|
|
|
|
#ifndef FUNCAPI_H
|
|
|
|
#define FUNCAPI_H
|
|
|
|
|
|
|
|
#include "postgres.h"
|
|
|
|
|
|
|
|
#include "fmgr.h"
|
|
|
|
#include "access/htup.h"
|
|
|
|
#include "access/tupdesc.h"
|
|
|
|
#include "executor/executor.h"
|
|
|
|
#include "executor/tuptable.h"
|
|
|
|
|
|
|
|
/*
|
|
|
|
* All functions that can be called directly by fmgr must have this signature.
|
|
|
|
* (Other functions can be called by using a handler that does have this
|
|
|
|
* signature.)
|
|
|
|
*/
|
|
|
|
|
|
|
|
|
|
|
|
/*-------------------------------------------------------------------------
|
|
|
|
* Support to ease writing Functions returning composite types
|
|
|
|
*-------------------------------------------------------------------------
|
|
|
|
*
|
|
|
|
* This struct holds arrays of individual attribute information
|
|
|
|
* needed to create a tuple from raw C strings. It also requires
|
|
|
|
* a copy of the TupleDesc. The information carried here
|
|
|
|
* is derived from the TupleDesc, but it is stored here to
|
|
|
|
* avoid redundant cpu cycles on each call to an SRF.
|
|
|
|
*/
|
|
|
|
typedef struct
|
|
|
|
{
|
|
|
|
/* full TupleDesc */
|
|
|
|
TupleDesc tupdesc;
|
|
|
|
|
|
|
|
/* pointer to array of attribute "type"in finfo */
|
|
|
|
FmgrInfo *attinfuncs;
|
|
|
|
|
|
|
|
/* pointer to array of attribute type typelem */
|
|
|
|
Oid *attelems;
|
|
|
|
|
|
|
|
/* pointer to array of attribute type typtypmod */
|
|
|
|
int4 *atttypmods;
|
|
|
|
|
|
|
|
} AttInMetadata;
|
|
|
|
|
|
|
|
/*-------------------------------------------------------------------------
|
|
|
|
* Support struct to ease writing Set Returning Functions (SRFs)
|
|
|
|
*-------------------------------------------------------------------------
|
|
|
|
*
|
|
|
|
* This struct holds function context for Set Returning Functions.
|
|
|
|
* Use fn_extra to hold a pointer to it across calls
|
|
|
|
*/
|
|
|
|
typedef struct
|
|
|
|
{
|
|
|
|
/* Number of times we've been called before */
|
2002-06-22 06:08:07 +02:00
|
|
|
uint32 call_cntr;
|
2002-06-20 22:39:04 +02:00
|
|
|
|
|
|
|
/* Maximum number of calls */
|
2002-06-22 06:08:07 +02:00
|
|
|
uint32 max_calls;
|
2002-06-20 22:39:04 +02:00
|
|
|
|
|
|
|
/* pointer to result slot */
|
|
|
|
TupleTableSlot *slot;
|
|
|
|
|
|
|
|
/* pointer to misc context info */
|
|
|
|
void *fctx;
|
|
|
|
|
|
|
|
/* pointer to struct containing arrays of attribute type input metainfo */
|
|
|
|
AttInMetadata *attinmeta;
|
|
|
|
|
|
|
|
/* memory context used to initialize structure */
|
|
|
|
MemoryContext fmctx;
|
|
|
|
|
|
|
|
} FuncCallContext;
|
|
|
|
|
|
|
|
/*-------------------------------------------------------------------------
|
|
|
|
* Support to ease writing Functions returning composite types
|
|
|
|
*
|
|
|
|
* External declarations:
|
|
|
|
* TupleDesc RelationNameGetTupleDesc(char *relname) - Use to get a TupleDesc
|
|
|
|
* based on the function's return type relation.
|
|
|
|
* TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases) - Use to get a
|
|
|
|
* TupleDesc based on the function's type oid. This can be used to get
|
|
|
|
* a TupleDesc for a base (scalar), or composite (relation) type.
|
|
|
|
* TupleTableSlot *TupleDescGetSlot(TupleDesc tupdesc) - Initialize a slot
|
|
|
|
* given a TupleDesc.
|
|
|
|
* AttInMetadata *TupleDescGetAttInMetadata(TupleDesc tupdesc) - Get a pointer
|
|
|
|
* to AttInMetadata based on the function's TupleDesc. AttInMetadata can
|
|
|
|
* be used in conjunction with C strings to produce a properly formed
|
|
|
|
* tuple. Store the metadata here for use across calls to avoid redundant
|
|
|
|
* work.
|
|
|
|
* HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values) -
|
|
|
|
* build a HeapTuple given user data in C string form. values is an array
|
|
|
|
* of C strings, one for each attribute of the return tuple.
|
|
|
|
*
|
|
|
|
* Macro declarations:
|
|
|
|
* TupleGetDatum(TupleTableSlot *slot, HeapTuple tuple) - get a Datum
|
|
|
|
* given a tuple and a slot.
|
|
|
|
*/
|
|
|
|
|
|
|
|
/* from tupdesc.c */
|
|
|
|
extern TupleDesc RelationNameGetTupleDesc(char *relname);
|
|
|
|
extern TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases);
|
|
|
|
|
|
|
|
/* from execTuples.c */
|
|
|
|
extern TupleTableSlot *TupleDescGetSlot(TupleDesc tupdesc);
|
|
|
|
extern AttInMetadata *TupleDescGetAttInMetadata(TupleDesc tupdesc);
|
|
|
|
extern HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values);
|
|
|
|
|
|
|
|
/* from funcapi.c */
|
|
|
|
extern void get_type_metadata(Oid typeid, Oid *attinfuncid, Oid *attelem);
|
|
|
|
|
|
|
|
#define TupleGetDatum(_slot, _tuple) \
|
|
|
|
PointerGetDatum(ExecStoreTuple(_tuple, _slot, InvalidBuffer, true))
|
|
|
|
|
|
|
|
/*-------------------------------------------------------------------------
|
|
|
|
* Support for Set Returning Functions (SRFs)
|
|
|
|
*
|
|
|
|
* The basic API for SRFs looks something like:
|
|
|
|
*
|
|
|
|
* Datum
|
|
|
|
* my_Set_Returning_Function(PG_FUNCTION_ARGS)
|
|
|
|
* {
|
|
|
|
* FuncCallContext *funcctx;
|
|
|
|
* Datum result;
|
|
|
|
* <user defined declarations>
|
|
|
|
*
|
|
|
|
* if(SRF_IS_FIRSTPASS())
|
|
|
|
* {
|
|
|
|
* <user defined code>
|
|
|
|
* funcctx = SRF_FIRSTCALL_INIT();
|
|
|
|
* <if returning composite>
|
|
|
|
* <obtain slot>
|
|
|
|
* funcctx->slot = slot;
|
|
|
|
* <endif returning composite>
|
|
|
|
* <user defined code>
|
|
|
|
* }
|
|
|
|
* <user defined code>
|
|
|
|
* funcctx = SRF_PERCALL_SETUP(funcctx);
|
|
|
|
* <user defined code>
|
|
|
|
*
|
|
|
|
* if (funcctx->call_cntr < funcctx->max_calls)
|
|
|
|
* {
|
|
|
|
* <user defined code>
|
|
|
|
* <obtain result Datum>
|
|
|
|
* SRF_RETURN_NEXT(funcctx, result);
|
|
|
|
* }
|
|
|
|
* else
|
|
|
|
* {
|
|
|
|
* SRF_RETURN_DONE(funcctx);
|
|
|
|
* }
|
|
|
|
* }
|
|
|
|
*
|
|
|
|
*/
|
|
|
|
|
|
|
|
/* from funcapi.c */
|
|
|
|
extern FuncCallContext *init_MultiFuncCall(PG_FUNCTION_ARGS);
|
|
|
|
extern void end_MultiFuncCall(PG_FUNCTION_ARGS, FuncCallContext *funcctx);
|
|
|
|
|
|
|
|
#define SRF_IS_FIRSTPASS() (fcinfo->flinfo->fn_extra == NULL)
|
|
|
|
#define SRF_FIRSTCALL_INIT() init_MultiFuncCall(fcinfo)
|
|
|
|
#define SRF_PERCALL_SETUP(_funcctx) \
|
|
|
|
fcinfo->flinfo->fn_extra; \
|
|
|
|
if(_funcctx->slot != NULL) \
|
|
|
|
ExecClearTuple(_funcctx->slot)
|
|
|
|
#define SRF_RETURN_NEXT(_funcctx, _result) \
|
|
|
|
do { \
|
|
|
|
ReturnSetInfo *rsi; \
|
|
|
|
_funcctx->call_cntr++; \
|
|
|
|
rsi = (ReturnSetInfo *) fcinfo->resultinfo; \
|
|
|
|
rsi->isDone = ExprMultipleResult; \
|
|
|
|
PG_RETURN_DATUM(_result); \
|
|
|
|
} while (0)
|
|
|
|
|
|
|
|
#define SRF_RETURN_DONE(_funcctx) \
|
|
|
|
do { \
|
|
|
|
ReturnSetInfo *rsi; \
|
|
|
|
end_MultiFuncCall(fcinfo, _funcctx); \
|
|
|
|
rsi = (ReturnSetInfo *) fcinfo->resultinfo; \
|
|
|
|
rsi->isDone = ExprEndResult; \
|
|
|
|
_funcctx->slot = NULL; \
|
|
|
|
PG_RETURN_NULL(); \
|
|
|
|
} while (0)
|
|
|
|
|
|
|
|
#endif /* FUNCAPI_H */
|