granicus.if.org Git - postgresql/blob - src/include/funcapi.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * funcapi.h
   4  *        Definitions for functions which return composite type and/or sets
   5  *        or work on VARIADIC inputs.
   6  *
   7  * This file must be included by all Postgres modules that either define
   8  * or call FUNCAPI-callable functions or macros.
   9  *
  10  *
  11  * Copyright (c) 2002-2017, PostgreSQL Global Development Group
  12  *
  13  * src/include/funcapi.h
  14  *
  15  *-------------------------------------------------------------------------
  16  */
  17 #ifndef FUNCAPI_H
  18 #define FUNCAPI_H
  19
  20 #include "fmgr.h"
  21 #include "access/tupdesc.h"
  22 #include "executor/executor.h"
  23 #include "executor/tuptable.h"
  24
  25
  26 /*-------------------------------------------------------------------------
  27  *      Support to ease writing Functions returning composite types
  28  *-------------------------------------------------------------------------
  29  *
  30  * This struct holds arrays of individual attribute information
  31  * needed to create a tuple from raw C strings. It also requires
  32  * a copy of the TupleDesc. The information carried here
  33  * is derived from the TupleDesc, but it is stored here to
  34  * avoid redundant cpu cycles on each call to an SRF.
  35  */
  36 typedef struct AttInMetadata
  37 {
  38         /* full TupleDesc */
  39         TupleDesc       tupdesc;
  40
  41         /* array of attribute type input function finfo */
  42         FmgrInfo   *attinfuncs;
  43
  44         /* array of attribute type i/o parameter OIDs */
  45         Oid                *attioparams;
  46
  47         /* array of attribute typmod */
  48         int32      *atttypmods;
  49 } AttInMetadata;
  50
  51 /*-------------------------------------------------------------------------
  52  *              Support struct to ease writing Set Returning Functions (SRFs)
  53  *-------------------------------------------------------------------------
  54  *
  55  * This struct holds function context for Set Returning Functions.
  56  * Use fn_extra to hold a pointer to it across calls
  57  */
  58 typedef struct FuncCallContext
  59 {
  60         /*
  61          * Number of times we've been called before
  62          *
  63          * call_cntr is initialized to 0 for you by SRF_FIRSTCALL_INIT(), and
  64          * incremented for you every time SRF_RETURN_NEXT() is called.
  65          */
  66         uint64          call_cntr;
  67
  68         /*
  69          * OPTIONAL maximum number of calls
  70          *
  71          * max_calls is here for convenience only and setting it is optional. If
  72          * not set, you must provide alternative means to know when the function
  73          * is done.
  74          */
  75         uint64          max_calls;
  76
  77         /*
  78          * OPTIONAL pointer to result slot
  79          *
  80          * This is obsolete and only present for backwards compatibility, viz,
  81          * user-defined SRFs that use the deprecated TupleDescGetSlot().
  82          */
  83         TupleTableSlot *slot;
  84
  85         /*
  86          * OPTIONAL pointer to miscellaneous user-provided context information
  87          *
  88          * user_fctx is for use as a pointer to your own struct to retain
  89          * arbitrary context information between calls of your function.
  90          */
  91         void       *user_fctx;
  92
  93         /*
  94          * OPTIONAL pointer to struct containing attribute type input metadata
  95          *
  96          * attinmeta is for use when returning tuples (i.e. composite data types)
  97          * and is not used when returning base data types. It is only needed if
  98          * you intend to use BuildTupleFromCStrings() to create the return tuple.
  99          */
 100         AttInMetadata *attinmeta;
 101
 102         /*
 103          * memory context used for structures that must live for multiple calls
 104          *
 105          * multi_call_memory_ctx is set by SRF_FIRSTCALL_INIT() for you, and used
 106          * by SRF_RETURN_DONE() for cleanup. It is the most appropriate memory
 107          * context for any memory that is to be reused across multiple calls of
 108          * the SRF.
 109          */
 110         MemoryContext multi_call_memory_ctx;
 111
 112         /*
 113          * OPTIONAL pointer to struct containing tuple description
 114          *
 115          * tuple_desc is for use when returning tuples (i.e. composite data types)
 116          * and is only needed if you are going to build the tuples with
 117          * heap_form_tuple() rather than with BuildTupleFromCStrings(). Note that
 118          * the TupleDesc pointer stored here should usually have been run through
 119          * BlessTupleDesc() first.
 120          */
 121         TupleDesc       tuple_desc;
 122
 123 } FuncCallContext;
 124
 125 /*----------
 126  *      Support to ease writing functions returning composite types
 127  *
 128  * External declarations:
 129  * get_call_result_type:
 130  *              Given a function's call info record, determine the kind of datatype
 131  *              it is supposed to return.  If resultTypeId isn't NULL, *resultTypeId
 132  *              receives the actual datatype OID (this is mainly useful for scalar
 133  *              result types).  If resultTupleDesc isn't NULL, *resultTupleDesc
 134  *              receives a pointer to a TupleDesc when the result is of a composite
 135  *              type, or NULL when it's a scalar result or the rowtype could not be
 136  *              determined.  NB: the tupledesc should be copied if it is to be
 137  *              accessed over a long period.
 138  * get_expr_result_type:
 139  *              Given an expression node, return the same info as for
 140  *              get_call_result_type.  Note: the cases in which rowtypes cannot be
 141  *              determined are different from the cases for get_call_result_type.
 142  * get_func_result_type:
 143  *              Given only a function's OID, return the same info as for
 144  *              get_call_result_type.  Note: the cases in which rowtypes cannot be
 145  *              determined are different from the cases for get_call_result_type.
 146  *              Do *not* use this if you can use one of the others.
 147  *
 148  * See also get_expr_result_tupdesc(), which is a convenient wrapper around
 149  * get_expr_result_type() for use when the caller only cares about
 150  * determinable-rowtype cases.
 151  *----------
 152  */
 153
 154 /* Type categories for get_call_result_type and siblings */
 155 typedef enum TypeFuncClass
 156 {
 157         TYPEFUNC_SCALAR,                        /* scalar result type */
 158         TYPEFUNC_COMPOSITE,                     /* determinable rowtype result */
 159         TYPEFUNC_COMPOSITE_DOMAIN,      /* domain over determinable rowtype result */
 160         TYPEFUNC_RECORD,                        /* indeterminate rowtype result */
 161         TYPEFUNC_OTHER                          /* bogus type, eg pseudotype */
 162 } TypeFuncClass;
 163
 164 extern TypeFuncClass get_call_result_type(FunctionCallInfo fcinfo,
 165                                          Oid *resultTypeId,
 166                                          TupleDesc *resultTupleDesc);
 167 extern TypeFuncClass get_expr_result_type(Node *expr,
 168                                          Oid *resultTypeId,
 169                                          TupleDesc *resultTupleDesc);
 170 extern TypeFuncClass get_func_result_type(Oid functionId,
 171                                          Oid *resultTypeId,
 172                                          TupleDesc *resultTupleDesc);
 173
 174 extern TupleDesc get_expr_result_tupdesc(Node *expr, bool noError);
 175
 176 extern bool resolve_polymorphic_argtypes(int numargs, Oid *argtypes,
 177                                                          char *argmodes,
 178                                                          Node *call_expr);
 179
 180 extern int get_func_arg_info(HeapTuple procTup,
 181                                   Oid **p_argtypes, char ***p_argnames,
 182                                   char **p_argmodes);
 183
 184 extern int get_func_input_arg_names(Datum proargnames, Datum proargmodes,
 185                                                  char ***arg_names);
 186
 187 extern int      get_func_trftypes(HeapTuple procTup, Oid **p_trftypes);
 188 extern char *get_func_result_name(Oid functionId);
 189
 190 extern TupleDesc build_function_result_tupdesc_d(Datum proallargtypes,
 191                                                                 Datum proargmodes,
 192                                                                 Datum proargnames);
 193 extern TupleDesc build_function_result_tupdesc_t(HeapTuple procTuple);
 194
 195
 196 /*----------
 197  *      Support to ease writing functions returning composite types
 198  *
 199  * External declarations:
 200  * TupleDesc BlessTupleDesc(TupleDesc tupdesc) - "Bless" a completed tuple
 201  *              descriptor so that it can be used to return properly labeled tuples.
 202  *              You need to call this if you are going to use heap_form_tuple directly.
 203  *              TupleDescGetAttInMetadata does it for you, however, so no need to call
 204  *              it if you call TupleDescGetAttInMetadata.
 205  * AttInMetadata *TupleDescGetAttInMetadata(TupleDesc tupdesc) - Build an
 206  *              AttInMetadata struct based on the given TupleDesc. AttInMetadata can
 207  *              be used in conjunction with C strings to produce a properly formed
 208  *              tuple.
 209  * HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values) -
 210  *              build a HeapTuple given user data in C string form. values is an array
 211  *              of C strings, one for each attribute of the return tuple.
 212  * Datum HeapTupleHeaderGetDatum(HeapTupleHeader tuple) - convert a
 213  *              HeapTupleHeader to a Datum.
 214  *
 215  * Macro declarations:
 216  * HeapTupleGetDatum(HeapTuple tuple) - convert a HeapTuple to a Datum.
 217  *
 218  * Obsolete routines and macros:
 219  * TupleDesc RelationNameGetTupleDesc(const char *relname) - Use to get a
 220  *              TupleDesc based on a named relation.
 221  * TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases) - Use to get a
 222  *              TupleDesc based on a type OID.
 223  * TupleTableSlot *TupleDescGetSlot(TupleDesc tupdesc) - Builds a
 224  *              TupleTableSlot, which is not needed anymore.
 225  * TupleGetDatum(TupleTableSlot *slot, HeapTuple tuple) - get a Datum
 226  *              given a tuple and a slot.
 227  *----------
 228  */
 229
 230 #define HeapTupleGetDatum(tuple)                HeapTupleHeaderGetDatum((tuple)->t_data)
 231 /* obsolete version of above */
 232 #define TupleGetDatum(_slot, _tuple)    HeapTupleGetDatum(_tuple)
 233
 234 extern TupleDesc RelationNameGetTupleDesc(const char *relname);
 235 extern TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases);
 236
 237 /* from execTuples.c */
 238 extern TupleDesc BlessTupleDesc(TupleDesc tupdesc);
 239 extern AttInMetadata *TupleDescGetAttInMetadata(TupleDesc tupdesc);
 240 extern HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values);
 241 extern Datum HeapTupleHeaderGetDatum(HeapTupleHeader tuple);
 242 extern TupleTableSlot *TupleDescGetSlot(TupleDesc tupdesc);
 243
 244
 245 /*----------
 246  *              Support for Set Returning Functions (SRFs)
 247  *
 248  * The basic API for SRFs looks something like:
 249  *
 250  * Datum
 251  * my_Set_Returning_Function(PG_FUNCTION_ARGS)
 252  * {
 253  *      FuncCallContext    *funcctx;
 254  *      Datum                           result;
 255  *      MemoryContext           oldcontext;
 256  *      <user defined declarations>
 257  *
 258  *      if (SRF_IS_FIRSTCALL())
 259  *      {
 260  *              funcctx = SRF_FIRSTCALL_INIT();
 261  *              // switch context when allocating stuff to be used in later calls
 262  *              oldcontext = MemoryContextSwitchTo(funcctx->multi_call_memory_ctx);
 263  *              <user defined code>
 264  *              <if returning composite>
 265  *                      <build TupleDesc, and perhaps AttInMetaData>
 266  *              <endif returning composite>
 267  *              <user defined code>
 268  *              // return to original context when allocating transient memory
 269  *              MemoryContextSwitchTo(oldcontext);
 270  *      }
 271  *      <user defined code>
 272  *      funcctx = SRF_PERCALL_SETUP();
 273  *      <user defined code>
 274  *
 275  *      if (funcctx->call_cntr < funcctx->max_calls)
 276  *      {
 277  *              <user defined code>
 278  *              <obtain result Datum>
 279  *              SRF_RETURN_NEXT(funcctx, result);
 280  *      }
 281  *      else
 282  *              SRF_RETURN_DONE(funcctx);
 283  * }
 284  *
 285  *----------
 286  */
 287
 288 /* from funcapi.c */
 289 extern FuncCallContext *init_MultiFuncCall(PG_FUNCTION_ARGS);
 290 extern FuncCallContext *per_MultiFuncCall(PG_FUNCTION_ARGS);
 291 extern void end_MultiFuncCall(PG_FUNCTION_ARGS, FuncCallContext *funcctx);
 292
 293 #define SRF_IS_FIRSTCALL() (fcinfo->flinfo->fn_extra == NULL)
 294
 295 #define SRF_FIRSTCALL_INIT() init_MultiFuncCall(fcinfo)
 296
 297 #define SRF_PERCALL_SETUP() per_MultiFuncCall(fcinfo)
 298
 299 #define SRF_RETURN_NEXT(_funcctx, _result) \
 300         do { \
 301                 ReturnSetInfo      *rsi; \
 302                 (_funcctx)->call_cntr++; \
 303                 rsi = (ReturnSetInfo *) fcinfo->resultinfo; \
 304                 rsi->isDone = ExprMultipleResult; \
 305                 PG_RETURN_DATUM(_result); \
 306         } while (0)
 307
 308 #define SRF_RETURN_NEXT_NULL(_funcctx) \
 309         do { \
 310                 ReturnSetInfo      *rsi; \
 311                 (_funcctx)->call_cntr++; \
 312                 rsi = (ReturnSetInfo *) fcinfo->resultinfo; \
 313                 rsi->isDone = ExprMultipleResult; \
 314                 PG_RETURN_NULL(); \
 315         } while (0)
 316
 317 #define  SRF_RETURN_DONE(_funcctx) \
 318         do { \
 319                 ReturnSetInfo      *rsi; \
 320                 end_MultiFuncCall(fcinfo, _funcctx); \
 321                 rsi = (ReturnSetInfo *) fcinfo->resultinfo; \
 322                 rsi->isDone = ExprEndResult; \
 323                 PG_RETURN_NULL(); \
 324         } while (0)
 325
 326 /*----------
 327  *      Support to ease writing of functions dealing with VARIADIC inputs
 328  *----------
 329  *
 330  * This function extracts a set of argument values, types and NULL markers
 331  * for a given input function. This returns a set of data:
 332  * - **values includes the set of Datum values extracted.
 333  * - **types the data type OID for each element.
 334  * - **nulls tracks if an element is NULL.
 335  *
 336  * variadic_start indicates the argument number where the VARIADIC argument
 337  * starts.
 338  * convert_unknown set to true will enforce the conversion of arguments
 339  * with unknown data type to text.
 340  *
 341  * The return result is the number of elements stored, or -1 in the case of
 342  * "VARIADIC NULL".
 343  */
 344 extern int extract_variadic_args(FunctionCallInfo fcinfo, int variadic_start,
 345                                           bool convert_unknown, Datum **values,
 346                                           Oid **types, bool **nulls);
 347
 348 #endif                                                  /* FUNCAPI_H */