LCOV - code coverage report
Current view: top level - src/include - funcapi.h (source / functions) Hit Total Coverage
Test: PostgreSQL 17devel Lines: 2 2 100.0 %
Date: 2024-02-28 23:11:08 Functions: 1 1 100.0 %
Legend: Lines: hit not hit

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

Generated by: LCOV version 1.14