postgres/src/include/utils/portal.h

/*-------------------------------------------------------------------------
 *
 * portal.h
 *	  POSTGRES portal definitions.
 *
 * A portal is an abstraction which represents the execution state of
 * a running query (specifically, a CURSOR).
 *
 * Portions Copyright (c) 1996-2002, PostgreSQL Global Development Group
 * Portions Copyright (c) 1994, Regents of the University of California
 *
 * $Id: portal.h,v 1.38 2003/03/10 03:53:52 tgl Exp $
 *
 *-------------------------------------------------------------------------
 */
#ifndef PORTAL_H
#define PORTAL_H

#include "executor/execdesc.h"
#include "nodes/memnodes.h"


typedef struct PortalData *Portal;

typedef struct PortalData
{
	char	   *name;			/* Portal's name */
	MemoryContext heap;			/* subsidiary memory */
	QueryDesc  *queryDesc;		/* Info about query associated with portal */
	bool		backwardOK;		/* is fetch backwards allowed at all? */
	bool		atStart;		/* T => fetch backwards is not allowed now */
	bool		atEnd;			/* T => fetch forwards is not allowed now */
	void		(*cleanup) (Portal);	/* Cleanup routine (optional) */
} PortalData;

/*
 * PortalIsValid
 *		True iff portal is valid.
 */
#define PortalIsValid(p) PointerIsValid(p)

/*
 * Access macros for Portal ... use these in preference to field access.
 */
#define PortalGetQueryDesc(portal)	((portal)->queryDesc)
#define PortalGetHeapMemory(portal) ((portal)->heap)


extern void EnablePortalManager(void);
extern void AtEOXact_portals(void);
extern Portal CreatePortal(const char *name);
extern void PortalDrop(Portal portal);
extern Portal GetPortalByName(const char *name);
extern void PortalSetQuery(Portal portal, QueryDesc *queryDesc,
						   void (*cleanup) (Portal portal));

#endif   /* PORTAL_H */
More cleanups of the include files - centralizing to simplify the -I's required to compile 30 years ago			`/*-------------------------------------------------------------------------`
			`*`
Change my-function-name-- to my_function_name, and optimizer renames. 27 years ago			`* portal.h`
Massive commit to run PGINDENT on all .c and .h files. 29 years ago			`* POSTGRES portal definitions.`
More cleanups of the include files - centralizing to simplify the -I's required to compile 30 years ago			`*`
Phase 1 of read-only-plans project: cause executor state nodes to point to plan nodes, not vice-versa. All executor state nodes now inherit from struct PlanState. Copying of plan trees has been simplified by not storing a list of SubPlans in Plan nodes (eliminating duplicate links). The executor still needs such a list, but it can build it during ExecutorStart since it has to scan the plan tree anyway. No initdb forced since no stored-on-disk structures changed, but you will need a full recompile because of node-numbering changes. 23 years ago			`* A portal is an abstraction which represents the execution state of`
			`* a running query (specifically, a CURSOR).`
More cleanups of the include files - centralizing to simplify the -I's required to compile 30 years ago			`*`
Update copyright to 2002. 24 years ago			`* Portions Copyright (c) 1996-2002, PostgreSQL Global Development Group`
Add: * Portions Copyright (c) 1996-2000, PostgreSQL, Inc to all files copyright Regents of Berkeley. Man, that's a lot of files. 26 years ago			`* Portions Copyright (c) 1994, Regents of the University of California`
More cleanups of the include files - centralizing to simplify the -I's required to compile 30 years ago			`*`
Restructure parsetree representation of DECLARE CURSOR: now it's a utility statement (DeclareCursorStmt) with a SELECT query dangling from it, rather than a SELECT query with a few unusual fields in it. Add code to determine whether a planned query can safely be run backwards. If DECLARE CURSOR specifies SCROLL, ensure that the plan can be run backwards by adding a Materialize plan node if it can't. Without SCROLL, you get an error if you try to fetch backwards from a cursor that can't handle it. (There is still some discussion about what the exact behavior should be, but this is necessary infrastructure in any case.) Along the way, make EXPLAIN DECLARE CURSOR work. 23 years ago			`* $Id: portal.h,v 1.38 2003/03/10 03:53:52 tgl Exp $`
More cleanups of the include files - centralizing to simplify the -I's required to compile 30 years ago			`*`
			`*-------------------------------------------------------------------------`
			`*/`
Massive commit to run PGINDENT on all .c and .h files. 29 years ago			`#ifndef PORTAL_H`
More cleanups of the include files - centralizing to simplify the -I's required to compile 30 years ago			`#define PORTAL_H`

Change #include's to use <> and "" as appropriate. 27 years ago			`#include "executor/execdesc.h"`
			`#include "nodes/memnodes.h"`
More cleanups of the include files - centralizing to simplify the -I's required to compile 30 years ago

Tweak portal (cursor) code so that it will not call the executor again when user does another FETCH after reaching end of data, or another FETCH backwards after reaching start. This is needed because some plan nodes are not very robust about being called again after they've already returned NULL; for example, MergeJoin will crash in some states but not others. While the ideal approach would be for them all to handle this correctly, it seems foolish to assume that no such bugs would creep in again once cleaned up. Therefore, the most robust answer is to prevent the situation from arising at all. 25 years ago			`typedef struct PortalData *Portal;`
More cleanups of the include files - centralizing to simplify the -I's required to compile 30 years ago
Tweak portal (cursor) code so that it will not call the executor again when user does another FETCH after reaching end of data, or another FETCH backwards after reaching start. This is needed because some plan nodes are not very robust about being called again after they've already returned NULL; for example, MergeJoin will crash in some states but not others. While the ideal approach would be for them all to handle this correctly, it seems foolish to assume that no such bugs would creep in again once cleaned up. Therefore, the most robust answer is to prevent the situation from arising at all. 25 years ago			`typedef struct PortalData`
Massive commit to run PGINDENT on all .c and .h files. 29 years ago			`{`
First phase of memory management rewrite (see backend/utils/mmgr/README for details). It doesn't really do that much yet, since there are no short-term memory contexts in the executor, but the infrastructure is in place and long-term contexts are handled reasonably. A few long- standing bugs have been fixed, such as 'VACUUM; anything' in a single query string crashing. Also, out-of-memory is now considered a recoverable ERROR, not FATAL. Eliminate a large amount of crufty, now-dead code in and around memory management. Fix problem with holding off SIGTRAP, SIGSEGV, etc in postmaster and backend startup. 26 years ago			`char name; / Portal's name */`
			`MemoryContext heap; /* subsidiary memory */`
			`QueryDesc queryDesc; / Info about query associated with portal */`
Restructure parsetree representation of DECLARE CURSOR: now it's a utility statement (DeclareCursorStmt) with a SELECT query dangling from it, rather than a SELECT query with a few unusual fields in it. Add code to determine whether a planned query can safely be run backwards. If DECLARE CURSOR specifies SCROLL, ensure that the plan can be run backwards by adding a Materialize plan node if it can't. Without SCROLL, you get an error if you try to fetch backwards from a cursor that can't handle it. (There is still some discussion about what the exact behavior should be, but this is necessary infrastructure in any case.) Along the way, make EXPLAIN DECLARE CURSOR work. 23 years ago			`bool backwardOK; /* is fetch backwards allowed at all? */`
			`bool atStart; /* T => fetch backwards is not allowed now */`
			`bool atEnd; /* T => fetch forwards is not allowed now */`
pgindent run. Make it all clean. 25 years ago			`void (cleanup) (Portal); / Cleanup routine (optional) */`
pgindent run on all C files. Java run to follow. initdb/regression tests pass. 25 years ago			`} PortalData;`
More cleanups of the include files - centralizing to simplify the -I's required to compile 30 years ago
			`/*`
pgindent run over code. 27 years ago			`* PortalIsValid`
Massive commit to run PGINDENT on all .c and .h files. 29 years ago			`* True iff portal is valid.`
More cleanups of the include files - centralizing to simplify the -I's required to compile 30 years ago			`*/`
Massive commit to run PGINDENT on all .c and .h files. 29 years ago			`#define PortalIsValid(p) PointerIsValid(p)`
More cleanups of the include files - centralizing to simplify the -I's required to compile 30 years ago
Tweak portal (cursor) code so that it will not call the executor again when user does another FETCH after reaching end of data, or another FETCH backwards after reaching start. This is needed because some plan nodes are not very robust about being called again after they've already returned NULL; for example, MergeJoin will crash in some states but not others. While the ideal approach would be for them all to handle this correctly, it seems foolish to assume that no such bugs would creep in again once cleaned up. Therefore, the most robust answer is to prevent the situation from arising at all. 25 years ago			`/*`
			`* Access macros for Portal ... use these in preference to field access.`
			`*/`
pgindent run. Make it all clean. 25 years ago			`#define PortalGetQueryDesc(portal) ((portal)->queryDesc)`
pgindent run. 24 years ago			`#define PortalGetHeapMemory(portal) ((portal)->heap)`
Tweak portal (cursor) code so that it will not call the executor again when user does another FETCH after reaching end of data, or another FETCH backwards after reaching start. This is needed because some plan nodes are not very robust about being called again after they've already returned NULL; for example, MergeJoin will crash in some states but not others. While the ideal approach would be for them all to handle this correctly, it seems foolish to assume that no such bugs would creep in again once cleaned up. Therefore, the most robust answer is to prevent the situation from arising at all. 25 years ago

First phase of memory management rewrite (see backend/utils/mmgr/README for details). It doesn't really do that much yet, since there are no short-term memory contexts in the executor, but the infrastructure is in place and long-term contexts are handled reasonably. A few long- standing bugs have been fixed, such as 'VACUUM; anything' in a single query string crashing. Also, out-of-memory is now considered a recoverable ERROR, not FATAL. Eliminate a large amount of crufty, now-dead code in and around memory management. Fix problem with holding off SIGTRAP, SIGSEGV, etc in postmaster and backend startup. 26 years ago			`extern void EnablePortalManager(void);`
Another PGINDENT run that changes variable indenting and case label indenting. Also static variable indenting. 29 years ago			`extern void AtEOXact_portals(void);`
Adjust Tcl-related code to compile cleanly with Tcl 8.4 (add const modifiers as needed). Some desultory const-ification of SPI interface to support this. 23 years ago			`extern Portal CreatePortal(const char *name);`
Further cleanup of dynahash.c API, in pursuit of portability and readability. Bizarre '(long *) TRUE' return convention is gone, in favor of just raising an error internally in dynahash.c when we detect hashtable corruption. HashTableWalk is gone, in favor of using hash_seq_search directly, since it had no hope of working with non-LONGALIGNable datatypes. Simplify some other code that was made undesirably grotty by promixity to HashTableWalk. 25 years ago			`extern void PortalDrop(Portal portal);`
Adjust Tcl-related code to compile cleanly with Tcl 8.4 (add const modifiers as needed). Some desultory const-ification of SPI interface to support this. 23 years ago			`extern Portal GetPortalByName(const char *name);`
OK, folks, here is the pgindent output. 28 years ago			`extern void PortalSetQuery(Portal portal, QueryDesc *queryDesc,`
Phase 1 of read-only-plans project: cause executor state nodes to point to plan nodes, not vice-versa. All executor state nodes now inherit from struct PlanState. Copying of plan trees has been simplified by not storing a list of SubPlans in Plan nodes (eliminating duplicate links). The executor still needs such a list, but it can build it during ExecutorStart since it has to scan the plan tree anyway. No initdb forced since no stored-on-disk structures changed, but you will need a full recompile because of node-numbering changes. 23 years ago			`void (*cleanup) (Portal portal));`
More cleanups of the include files - centralizing to simplify the -I's required to compile 30 years ago
New pgindent run with fixes suggested by Tom. Patch manually reviewed, initdb/regression tests pass. 24 years ago			`#endif /* PORTAL_H */`