@@ -65,22 +65,57 @@ typedef struct
6565 */
6666typedef struct
6767{
68- /* Number of times we've been called before */
68+ /*
69+ * Number of times we've been called before.
70+ *
71+ * call_cntr is initialized to 0 for you by SRF_FIRSTCALL_INIT(), and
72+ * incremented for you every time SRF_RETURN_NEXT() is called.
73+ */
6974uint32 call_cntr ;
7075
71- /* Maximum number of calls */
76+ /*
77+ * OPTIONAL maximum number of calls
78+ *
79+ * max_calls is here for convenience ONLY and setting it is OPTIONAL.
80+ * If not set, you must provide alternative means to know when the
81+ * function is done.
82+ */
7283uint32 max_calls ;
7384
74- /* pointer to result slot */
85+ /*
86+ * OPTIONAL pointer to result slot
87+ *
88+ * slot is for use when returning tuples (i.e. composite data types)
89+ * and is not needed when returning base (i.e. scalar) data types.
90+ */
7591TupleTableSlot * slot ;
7692
77- /* pointer to misc context info */
78- void * fctx ;
79-
80- /* pointer to struct containing arrays of attribute type input metainfo */
93+ /*
94+ * OPTIONAL pointer to misc user provided context info
95+ *
96+ * user_fctx is for use as a pointer to your own struct to retain
97+ * arbitrary context information between calls for your function.
98+ */
99+ void * user_fctx ;
100+
101+ /*
102+ * OPTIONAL pointer to struct containing arrays of attribute type input
103+ * metainfo
104+ *
105+ * attinmeta is for use when returning tuples (i.e. composite data types)
106+ * and is not needed when returning base (i.e. scalar) data types. It
107+ * is ONLY needed if you intend to use BuildTupleFromCStrings() to create
108+ * the return tuple.
109+ */
81110AttInMetadata * attinmeta ;
82111
83- /* memory context used to initialize structure */
112+ /*
113+ * memory context used to initialize structure
114+ *
115+ * fmctx is set by SRF_FIRSTCALL_INIT() for you, and used by
116+ * SRF_RETURN_DONE() for cleanup. It is primarily for internal use
117+ * by the API.
118+ */
84119MemoryContext fmctx ;
85120
86121}FuncCallContext ;
@@ -137,7 +172,7 @@ extern void get_type_metadata(Oid typeid, Oid *attinfuncid, Oid *attelem);
137172 * Datumresult;
138173 * <user defined declarations>
139174 *
140- * if(SRF_IS_FIRSTPASS ())
175+ * if(SRF_IS_FIRSTCALL ())
141176 * {
142177 * <user defined code>
143178 * funcctx = SRF_FIRSTCALL_INIT();
@@ -148,7 +183,7 @@ extern void get_type_metadata(Oid typeid, Oid *attinfuncid, Oid *attelem);
148183 * <user defined code>
149184 * }
150185 * <user defined code>
151- * funcctx = SRF_PERCALL_SETUP(funcctx );
186+ * funcctx = SRF_PERCALL_SETUP();
152187 * <user defined code>
153188 *
154189 * if (funcctx->call_cntr < funcctx->max_calls)
@@ -167,14 +202,12 @@ extern void get_type_metadata(Oid typeid, Oid *attinfuncid, Oid *attelem);
167202
168203/* from funcapi.c */
169204extern FuncCallContext * init_MultiFuncCall (PG_FUNCTION_ARGS );
205+ extern FuncCallContext * per_MultiFuncCall (PG_FUNCTION_ARGS );
170206extern void end_MultiFuncCall (PG_FUNCTION_ARGS ,FuncCallContext * funcctx );
171207
172- #define SRF_IS_FIRSTPASS () (fcinfo->flinfo->fn_extra == NULL)
208+ #define SRF_IS_FIRSTCALL () (fcinfo->flinfo->fn_extra == NULL)
173209#define SRF_FIRSTCALL_INIT () init_MultiFuncCall(fcinfo)
174- #define SRF_PERCALL_SETUP (_funcctx ) \
175- fcinfo->flinfo->fn_extra; \
176- if(_funcctx->slot != NULL) \
177- ExecClearTuple(_funcctx->slot)
210+ #define SRF_PERCALL_SETUP () per_MultiFuncCall(fcinfo)
178211#define SRF_RETURN_NEXT (_funcctx ,_result ) \
179212do { \
180213ReturnSetInfo *rsi; \