pg_query 2.0.0 → 2.0.1

data/ext/pg_query/include/utils/syscache.h

@@ -0,0 +1,219 @@
+/*-------------------------------------------------------------------------
+ *
+ * syscache.h
+ *	  System catalog cache definitions.
+ *
+ * See also lsyscache.h, which provides convenience routines for
+ * common cache-lookup operations.
+ *
+ * Portions Copyright (c) 1996-2020, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1994, Regents of the University of California
+ *
+ * src/include/utils/syscache.h
+ *
+ *-------------------------------------------------------------------------
+ */
+#ifndef SYSCACHE_H
+#define SYSCACHE_H
+
+#include "access/attnum.h"
+#include "access/htup.h"
+/* we intentionally do not include utils/catcache.h here */
+
+/*
+ *		SysCache identifiers.
+ *
+ *		The order of these identifiers must match the order
+ *		of the entries in the array cacheinfo[] in syscache.c.
+ *		Keep them in alphabetical order (renumbering only costs a
+ *		backend rebuild).
+ */
+
+enum SysCacheIdentifier
+{
+	AGGFNOID = 0,
+	AMNAME,
+	AMOID,
+	AMOPOPID,
+	AMOPSTRATEGY,
+	AMPROCNUM,
+	ATTNAME,
+	ATTNUM,
+	AUTHMEMMEMROLE,
+	AUTHMEMROLEMEM,
+	AUTHNAME,
+	AUTHOID,
+	CASTSOURCETARGET,
+	CLAAMNAMENSP,
+	CLAOID,
+	COLLNAMEENCNSP,
+	COLLOID,
+	CONDEFAULT,
+	CONNAMENSP,
+	CONSTROID,
+	CONVOID,
+	DATABASEOID,
+	DEFACLROLENSPOBJ,
+	ENUMOID,
+	ENUMTYPOIDNAME,
+	EVENTTRIGGERNAME,
+	EVENTTRIGGEROID,
+	FOREIGNDATAWRAPPERNAME,
+	FOREIGNDATAWRAPPEROID,
+	FOREIGNSERVERNAME,
+	FOREIGNSERVEROID,
+	FOREIGNTABLEREL,
+	INDEXRELID,
+	LANGNAME,
+	LANGOID,
+	NAMESPACENAME,
+	NAMESPACEOID,
+	OPERNAMENSP,
+	OPEROID,
+	OPFAMILYAMNAMENSP,
+	OPFAMILYOID,
+	PARTRELID,
+	PROCNAMEARGSNSP,
+	PROCOID,
+	PUBLICATIONNAME,
+	PUBLICATIONOID,
+	PUBLICATIONREL,
+	PUBLICATIONRELMAP,
+	RANGETYPE,
+	RELNAMENSP,
+	RELOID,
+	REPLORIGIDENT,
+	REPLORIGNAME,
+	RULERELNAME,
+	SEQRELID,
+	STATEXTDATASTXOID,
+	STATEXTNAMENSP,
+	STATEXTOID,
+	STATRELATTINH,
+	SUBSCRIPTIONNAME,
+	SUBSCRIPTIONOID,
+	SUBSCRIPTIONRELMAP,
+	TABLESPACEOID,
+	TRFOID,
+	TRFTYPELANG,
+	TSCONFIGMAP,
+	TSCONFIGNAMENSP,
+	TSCONFIGOID,
+	TSDICTNAMENSP,
+	TSDICTOID,
+	TSPARSERNAMENSP,
+	TSPARSEROID,
+	TSTEMPLATENAMENSP,
+	TSTEMPLATEOID,
+	TYPENAMENSP,
+	TYPEOID,
+	USERMAPPINGOID,
+	USERMAPPINGUSERSERVER
+
+#define SysCacheSize (USERMAPPINGUSERSERVER + 1)
+};
+
+extern void InitCatalogCache(void);
+extern void InitCatalogCachePhase2(void);
+
+extern HeapTuple SearchSysCache(int cacheId,
+								Datum key1, Datum key2, Datum key3, Datum key4);
+
+/*
+ * The use of argument specific numbers is encouraged. They're faster, and
+ * insulates the caller from changes in the maximum number of keys.
+ */
+extern HeapTuple SearchSysCache1(int cacheId,
+								 Datum key1);
+extern HeapTuple SearchSysCache2(int cacheId,
+								 Datum key1, Datum key2);
+extern HeapTuple SearchSysCache3(int cacheId,
+								 Datum key1, Datum key2, Datum key3);
+extern HeapTuple SearchSysCache4(int cacheId,
+								 Datum key1, Datum key2, Datum key3, Datum key4);
+
+extern void ReleaseSysCache(HeapTuple tuple);
+
+/* convenience routines */
+extern HeapTuple SearchSysCacheCopy(int cacheId,
+									Datum key1, Datum key2, Datum key3, Datum key4);
+extern bool SearchSysCacheExists(int cacheId,
+								 Datum key1, Datum key2, Datum key3, Datum key4);
+extern Oid	GetSysCacheOid(int cacheId, AttrNumber oidcol,
+						   Datum key1, Datum key2, Datum key3, Datum key4);
+
+extern HeapTuple SearchSysCacheAttName(Oid relid, const char *attname);
+extern HeapTuple SearchSysCacheCopyAttName(Oid relid, const char *attname);
+extern bool SearchSysCacheExistsAttName(Oid relid, const char *attname);
+
+extern HeapTuple SearchSysCacheAttNum(Oid relid, int16 attnum);
+extern HeapTuple SearchSysCacheCopyAttNum(Oid relid, int16 attnum);
+
+extern Datum SysCacheGetAttr(int cacheId, HeapTuple tup,
+							 AttrNumber attributeNumber, bool *isNull);
+
+extern uint32 GetSysCacheHashValue(int cacheId,
+								   Datum key1, Datum key2, Datum key3, Datum key4);
+
+/* list-search interface.  Users of this must import catcache.h too */
+struct catclist;
+extern struct catclist *SearchSysCacheList(int cacheId, int nkeys,
+										   Datum key1, Datum key2, Datum key3);
+
+extern void SysCacheInvalidate(int cacheId, uint32 hashValue);
+
+extern bool RelationInvalidatesSnapshotsOnly(Oid relid);
+extern bool RelationHasSysCache(Oid relid);
+extern bool RelationSupportsSysCache(Oid relid);
+
+/*
+ * The use of the macros below rather than direct calls to the corresponding
+ * functions is encouraged, as it insulates the caller from changes in the
+ * maximum number of keys.
+ */
+#define SearchSysCacheCopy1(cacheId, key1) \
+	SearchSysCacheCopy(cacheId, key1, 0, 0, 0)
+#define SearchSysCacheCopy2(cacheId, key1, key2) \
+	SearchSysCacheCopy(cacheId, key1, key2, 0, 0)
+#define SearchSysCacheCopy3(cacheId, key1, key2, key3) \
+	SearchSysCacheCopy(cacheId, key1, key2, key3, 0)
+#define SearchSysCacheCopy4(cacheId, key1, key2, key3, key4) \
+	SearchSysCacheCopy(cacheId, key1, key2, key3, key4)
+
+#define SearchSysCacheExists1(cacheId, key1) \
+	SearchSysCacheExists(cacheId, key1, 0, 0, 0)
+#define SearchSysCacheExists2(cacheId, key1, key2) \
+	SearchSysCacheExists(cacheId, key1, key2, 0, 0)
+#define SearchSysCacheExists3(cacheId, key1, key2, key3) \
+	SearchSysCacheExists(cacheId, key1, key2, key3, 0)
+#define SearchSysCacheExists4(cacheId, key1, key2, key3, key4) \
+	SearchSysCacheExists(cacheId, key1, key2, key3, key4)
+
+#define GetSysCacheOid1(cacheId, oidcol, key1) \
+	GetSysCacheOid(cacheId, oidcol, key1, 0, 0, 0)
+#define GetSysCacheOid2(cacheId, oidcol, key1, key2) \
+	GetSysCacheOid(cacheId, oidcol, key1, key2, 0, 0)
+#define GetSysCacheOid3(cacheId, oidcol, key1, key2, key3) \
+	GetSysCacheOid(cacheId, oidcol, key1, key2, key3, 0)
+#define GetSysCacheOid4(cacheId, oidcol, key1, key2, key3, key4) \
+	GetSysCacheOid(cacheId, oidcol, key1, key2, key3, key4)
+
+#define GetSysCacheHashValue1(cacheId, key1) \
+	GetSysCacheHashValue(cacheId, key1, 0, 0, 0)
+#define GetSysCacheHashValue2(cacheId, key1, key2) \
+	GetSysCacheHashValue(cacheId, key1, key2, 0, 0)
+#define GetSysCacheHashValue3(cacheId, key1, key2, key3) \
+	GetSysCacheHashValue(cacheId, key1, key2, key3, 0)
+#define GetSysCacheHashValue4(cacheId, key1, key2, key3, key4) \
+	GetSysCacheHashValue(cacheId, key1, key2, key3, key4)
+
+#define SearchSysCacheList1(cacheId, key1) \
+	SearchSysCacheList(cacheId, 1, key1, 0, 0)
+#define SearchSysCacheList2(cacheId, key1, key2) \
+	SearchSysCacheList(cacheId, 2, key1, key2, 0)
+#define SearchSysCacheList3(cacheId, key1, key2, key3) \
+	SearchSysCacheList(cacheId, 3, key1, key2, key3)
+
+#define ReleaseSysCacheList(x)	ReleaseCatCacheList(x)
+
+#endif							/* SYSCACHE_H */

data/ext/pg_query/include/utils/timeout.h

@@ -0,0 +1,88 @@
+/*-------------------------------------------------------------------------
+ *
+ * timeout.h
+ *	  Routines to multiplex SIGALRM interrupts for multiple timeout reasons.
+ *
+ *
+ * Portions Copyright (c) 1996-2020, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1994, Regents of the University of California
+ *
+ * src/include/utils/timeout.h
+ *
+ *-------------------------------------------------------------------------
+ */
+#ifndef TIMEOUT_H
+#define TIMEOUT_H
+
+#include "datatype/timestamp.h"
+
+/*
+ * Identifiers for timeout reasons.  Note that in case multiple timeouts
+ * trigger at the same time, they are serviced in the order of this enum.
+ */
+typedef enum TimeoutId
+{
+	/* Predefined timeout reasons */
+	STARTUP_PACKET_TIMEOUT,
+	DEADLOCK_TIMEOUT,
+	LOCK_TIMEOUT,
+	STATEMENT_TIMEOUT,
+	STANDBY_DEADLOCK_TIMEOUT,
+	STANDBY_TIMEOUT,
+	STANDBY_LOCK_TIMEOUT,
+	IDLE_IN_TRANSACTION_SESSION_TIMEOUT,
+	/* First user-definable timeout reason */
+	USER_TIMEOUT,
+	/* Maximum number of timeout reasons */
+	MAX_TIMEOUTS = 16
+} TimeoutId;
+
+/* callback function signature */
+typedef void (*timeout_handler_proc) (void);
+
+/*
+ * Parameter structure for setting multiple timeouts at once
+ */
+typedef enum TimeoutType
+{
+	TMPARAM_AFTER,
+	TMPARAM_AT
+} TimeoutType;
+
+typedef struct
+{
+	TimeoutId	id;				/* timeout to set */
+	TimeoutType type;			/* TMPARAM_AFTER or TMPARAM_AT */
+	int			delay_ms;		/* only used for TMPARAM_AFTER */
+	TimestampTz fin_time;		/* only used for TMPARAM_AT */
+} EnableTimeoutParams;
+
+/*
+ * Parameter structure for clearing multiple timeouts at once
+ */
+typedef struct
+{
+	TimeoutId	id;				/* timeout to clear */
+	bool		keep_indicator; /* keep the indicator flag? */
+} DisableTimeoutParams;
+
+/* timeout setup */
+extern void InitializeTimeouts(void);
+extern TimeoutId RegisterTimeout(TimeoutId id, timeout_handler_proc handler);
+extern void reschedule_timeouts(void);
+
+/* timeout operation */
+extern void enable_timeout_after(TimeoutId id, int delay_ms);
+extern void enable_timeout_at(TimeoutId id, TimestampTz fin_time);
+extern void enable_timeouts(const EnableTimeoutParams *timeouts, int count);
+extern void disable_timeout(TimeoutId id, bool keep_indicator);
+extern void disable_timeouts(const DisableTimeoutParams *timeouts, int count);
+extern void disable_all_timeouts(bool keep_indicators);
+
+/* accessors */
+extern bool get_timeout_active(TimeoutId id);
+extern bool get_timeout_indicator(TimeoutId id, bool reset_indicator);
+extern TimestampTz get_timeout_start_time(TimeoutId id);
+extern TimestampTz get_timeout_finish_time(TimeoutId id);
+
+#endif							/* TIMEOUT_H */

data/ext/pg_query/include/utils/timestamp.h

@@ -0,0 +1,116 @@
+/*-------------------------------------------------------------------------
+ *
+ * timestamp.h
+ *	  Definitions for the SQL "timestamp" and "interval" types.
+ *
+ * Portions Copyright (c) 1996-2020, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1994, Regents of the University of California
+ *
+ * src/include/utils/timestamp.h
+ *
+ *-------------------------------------------------------------------------
+ */
+#ifndef TIMESTAMP_H
+#define TIMESTAMP_H
+
+#include "datatype/timestamp.h"
+#include "fmgr.h"
+#include "pgtime.h"
+
+
+/*
+ * Macros for fmgr-callable functions.
+ *
+ * For Timestamp, we make use of the same support routines as for int64.
+ * Therefore Timestamp is pass-by-reference if and only if int64 is!
+ */
+#define DatumGetTimestamp(X)  ((Timestamp) DatumGetInt64(X))
+#define DatumGetTimestampTz(X)	((TimestampTz) DatumGetInt64(X))
+#define DatumGetIntervalP(X)  ((Interval *) DatumGetPointer(X))
+
+#define TimestampGetDatum(X) Int64GetDatum(X)
+#define TimestampTzGetDatum(X) Int64GetDatum(X)
+#define IntervalPGetDatum(X) PointerGetDatum(X)
+
+#define PG_GETARG_TIMESTAMP(n) DatumGetTimestamp(PG_GETARG_DATUM(n))
+#define PG_GETARG_TIMESTAMPTZ(n) DatumGetTimestampTz(PG_GETARG_DATUM(n))
+#define PG_GETARG_INTERVAL_P(n) DatumGetIntervalP(PG_GETARG_DATUM(n))
+
+#define PG_RETURN_TIMESTAMP(x) return TimestampGetDatum(x)
+#define PG_RETURN_TIMESTAMPTZ(x) return TimestampTzGetDatum(x)
+#define PG_RETURN_INTERVAL_P(x) return IntervalPGetDatum(x)
+
+
+#define TIMESTAMP_MASK(b) (1 << (b))
+#define INTERVAL_MASK(b) (1 << (b))
+
+/* Macros to handle packing and unpacking the typmod field for intervals */
+#define INTERVAL_FULL_RANGE (0x7FFF)
+#define INTERVAL_RANGE_MASK (0x7FFF)
+#define INTERVAL_FULL_PRECISION (0xFFFF)
+#define INTERVAL_PRECISION_MASK (0xFFFF)
+#define INTERVAL_TYPMOD(p,r) ((((r) & INTERVAL_RANGE_MASK) << 16) | ((p) & INTERVAL_PRECISION_MASK))
+#define INTERVAL_PRECISION(t) ((t) & INTERVAL_PRECISION_MASK)
+#define INTERVAL_RANGE(t) (((t) >> 16) & INTERVAL_RANGE_MASK)
+
+#define TimestampTzPlusMilliseconds(tz,ms) ((tz) + ((ms) * (int64) 1000))
+
+
+/* Set at postmaster start */
+extern TimestampTz PgStartTime;
+
+/* Set at configuration reload */
+extern TimestampTz PgReloadTime;
+
+
+/* Internal routines (not fmgr-callable) */
+
+extern int32 anytimestamp_typmod_check(bool istz, int32 typmod);
+
+extern TimestampTz GetCurrentTimestamp(void);
+extern TimestampTz GetSQLCurrentTimestamp(int32 typmod);
+extern Timestamp GetSQLLocalTimestamp(int32 typmod);
+extern void TimestampDifference(TimestampTz start_time, TimestampTz stop_time,
+								long *secs, int *microsecs);
+extern long TimestampDifferenceMilliseconds(TimestampTz start_time,
+											TimestampTz stop_time);
+extern bool TimestampDifferenceExceeds(TimestampTz start_time,
+									   TimestampTz stop_time,
+									   int msec);
+
+extern TimestampTz time_t_to_timestamptz(pg_time_t tm);
+extern pg_time_t timestamptz_to_time_t(TimestampTz t);
+
+extern const char *timestamptz_to_str(TimestampTz t);
+
+extern int	tm2timestamp(struct pg_tm *tm, fsec_t fsec, int *tzp, Timestamp *dt);
+extern int	timestamp2tm(Timestamp dt, int *tzp, struct pg_tm *tm,
+						 fsec_t *fsec, const char **tzn, pg_tz *attimezone);
+extern void dt2time(Timestamp dt, int *hour, int *min, int *sec, fsec_t *fsec);
+
+extern int	interval2tm(Interval span, struct pg_tm *tm, fsec_t *fsec);
+extern int	tm2interval(struct pg_tm *tm, fsec_t fsec, Interval *span);
+
+extern Timestamp SetEpochTimestamp(void);
+extern void GetEpochTime(struct pg_tm *tm);
+
+extern int	timestamp_cmp_internal(Timestamp dt1, Timestamp dt2);
+
+/* timestamp comparison works for timestamptz also */
+#define timestamptz_cmp_internal(dt1,dt2)	timestamp_cmp_internal(dt1, dt2)
+
+extern TimestampTz timestamp2timestamptz_opt_overflow(Timestamp timestamp,
+													  int *overflow);
+extern int32 timestamp_cmp_timestamptz_internal(Timestamp timestampVal,
+												TimestampTz dt2);
+
+extern int	isoweek2j(int year, int week);
+extern void isoweek2date(int woy, int *year, int *mon, int *mday);
+extern void isoweekdate2date(int isoweek, int wday, int *year, int *mon, int *mday);
+extern int	date2isoweek(int year, int mon, int mday);
+extern int	date2isoyear(int year, int mon, int mday);
+extern int	date2isoyearday(int year, int mon, int mday);
+
+extern bool TimestampTimestampTzRequiresRewrite(void);
+
+#endif							/* TIMESTAMP_H */

data/ext/pg_query/include/utils/tuplesort.h

@@ -0,0 +1,277 @@
+/*-------------------------------------------------------------------------
+ *
+ * tuplesort.h
+ *	  Generalized tuple sorting routines.
+ *
+ * This module handles sorting of heap tuples, index tuples, or single
+ * Datums (and could easily support other kinds of sortable objects,
+ * if necessary).  It works efficiently for both small and large amounts
+ * of data.  Small amounts are sorted in-memory using qsort().  Large
+ * amounts are sorted using temporary files and a standard external sort
+ * algorithm.  Parallel sorts use a variant of this external sort
+ * algorithm, and are typically only used for large amounts of data.
+ *
+ * Portions Copyright (c) 1996-2020, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1994, Regents of the University of California
+ *
+ * src/include/utils/tuplesort.h
+ *
+ *-------------------------------------------------------------------------
+ */
+#ifndef TUPLESORT_H
+#define TUPLESORT_H
+
+#include "access/itup.h"
+#include "executor/tuptable.h"
+#include "storage/dsm.h"
+#include "utils/relcache.h"
+
+
+/*
+ * Tuplesortstate and Sharedsort are opaque types whose details are not
+ * known outside tuplesort.c.
+ */
+typedef struct Tuplesortstate Tuplesortstate;
+typedef struct Sharedsort Sharedsort;
+
+/*
+ * Tuplesort parallel coordination state, allocated by each participant in
+ * local memory.  Participant caller initializes everything.  See usage notes
+ * below.
+ */
+typedef struct SortCoordinateData
+{
+	/* Worker process?  If not, must be leader. */
+	bool		isWorker;
+
+	/*
+	 * Leader-process-passed number of participants known launched (workers
+	 * set this to -1).  Includes state within leader needed for it to
+	 * participate as a worker, if any.
+	 */
+	int			nParticipants;
+
+	/* Private opaque state (points to shared memory) */
+	Sharedsort *sharedsort;
+}			SortCoordinateData;
+
+typedef struct SortCoordinateData *SortCoordinate;
+
+/*
+ * Data structures for reporting sort statistics.  Note that
+ * TuplesortInstrumentation can't contain any pointers because we
+ * sometimes put it in shared memory.
+ *
+ * The parallel-sort infrastructure relies on having a zero TuplesortMethod
+ * to indicate that a worker never did anything, so we assign zero to
+ * SORT_TYPE_STILL_IN_PROGRESS.  The other values of this enum can be
+ * OR'ed together to represent a situation where different workers used
+ * different methods, so we need a separate bit for each one.  Keep the
+ * NUM_TUPLESORTMETHODS constant in sync with the number of bits!
+ */
+typedef enum
+{
+	SORT_TYPE_STILL_IN_PROGRESS = 0,
+	SORT_TYPE_TOP_N_HEAPSORT = 1 << 0,
+	SORT_TYPE_QUICKSORT = 1 << 1,
+	SORT_TYPE_EXTERNAL_SORT = 1 << 2,
+	SORT_TYPE_EXTERNAL_MERGE = 1 << 3
+} TuplesortMethod;
+
+#define NUM_TUPLESORTMETHODS 4
+
+typedef enum
+{
+	SORT_SPACE_TYPE_DISK,
+	SORT_SPACE_TYPE_MEMORY
+} TuplesortSpaceType;
+
+typedef struct TuplesortInstrumentation
+{
+	TuplesortMethod sortMethod; /* sort algorithm used */
+	TuplesortSpaceType spaceType;	/* type of space spaceUsed represents */
+	int64		spaceUsed;		/* space consumption, in kB */
+} TuplesortInstrumentation;
+
+
+/*
+ * We provide multiple interfaces to what is essentially the same code,
+ * since different callers have different data to be sorted and want to
+ * specify the sort key information differently.  There are two APIs for
+ * sorting HeapTuples and two more for sorting IndexTuples.  Yet another
+ * API supports sorting bare Datums.
+ *
+ * Serial sort callers should pass NULL for their coordinate argument.
+ *
+ * The "heap" API actually stores/sorts MinimalTuples, which means it doesn't
+ * preserve the system columns (tuple identity and transaction visibility
+ * info).  The sort keys are specified by column numbers within the tuples
+ * and sort operator OIDs.  We save some cycles by passing and returning the
+ * tuples in TupleTableSlots, rather than forming actual HeapTuples (which'd
+ * have to be converted to MinimalTuples).  This API works well for sorts
+ * executed as parts of plan trees.
+ *
+ * The "cluster" API stores/sorts full HeapTuples including all visibility
+ * info. The sort keys are specified by reference to a btree index that is
+ * defined on the relation to be sorted.  Note that putheaptuple/getheaptuple
+ * go with this API, not the "begin_heap" one!
+ *
+ * The "index_btree" API stores/sorts IndexTuples (preserving all their
+ * header fields).  The sort keys are specified by a btree index definition.
+ *
+ * The "index_hash" API is similar to index_btree, but the tuples are
+ * actually sorted by their hash codes not the raw data.
+ *
+ * Parallel sort callers are required to coordinate multiple tuplesort states
+ * in a leader process and one or more worker processes.  The leader process
+ * must launch workers, and have each perform an independent "partial"
+ * tuplesort, typically fed by the parallel heap interface.  The leader later
+ * produces the final output (internally, it merges runs output by workers).
+ *
+ * Callers must do the following to perform a sort in parallel using multiple
+ * worker processes:
+ *
+ * 1. Request tuplesort-private shared memory for n workers.  Use
+ *    tuplesort_estimate_shared() to get the required size.
+ * 2. Have leader process initialize allocated shared memory using
+ *    tuplesort_initialize_shared().  Launch workers.
+ * 3. Initialize a coordinate argument within both the leader process, and
+ *    for each worker process.  This has a pointer to the shared
+ *    tuplesort-private structure, as well as some caller-initialized fields.
+ *    Leader's coordinate argument reliably indicates number of workers
+ *    launched (this is unused by workers).
+ * 4. Begin a tuplesort using some appropriate tuplesort_begin* routine,
+ *    (passing the coordinate argument) within each worker.  The workMem
+ *    arguments need not be identical.  All other arguments should match
+ *    exactly, though.
+ * 5. tuplesort_attach_shared() should be called by all workers.  Feed tuples
+ *    to each worker, and call tuplesort_performsort() within each when input
+ *    is exhausted.
+ * 6. Call tuplesort_end() in each worker process.  Worker processes can shut
+ *    down once tuplesort_end() returns.
+ * 7. Begin a tuplesort in the leader using the same tuplesort_begin*
+ *    routine, passing a leader-appropriate coordinate argument (this can
+ *    happen as early as during step 3, actually, since we only need to know
+ *    the number of workers successfully launched).  The leader must now wait
+ *    for workers to finish.  Caller must use own mechanism for ensuring that
+ *    next step isn't reached until all workers have called and returned from
+ *    tuplesort_performsort().  (Note that it's okay if workers have already
+ *    also called tuplesort_end() by then.)
+ * 8. Call tuplesort_performsort() in leader.  Consume output using the
+ *    appropriate tuplesort_get* routine.  Leader can skip this step if
+ *    tuplesort turns out to be unnecessary.
+ * 9. Call tuplesort_end() in leader.
+ *
+ * This division of labor assumes nothing about how input tuples are produced,
+ * but does require that caller combine the state of multiple tuplesorts for
+ * any purpose other than producing the final output.  For example, callers
+ * must consider that tuplesort_get_stats() reports on only one worker's role
+ * in a sort (or the leader's role), and not statistics for the sort as a
+ * whole.
+ *
+ * Note that callers may use the leader process to sort runs as if it was an
+ * independent worker process (prior to the process performing a leader sort
+ * to produce the final sorted output).  Doing so only requires a second
+ * "partial" tuplesort within the leader process, initialized like that of a
+ * worker process.  The steps above don't touch on this directly.  The only
+ * difference is that the tuplesort_attach_shared() call is never needed within
+ * leader process, because the backend as a whole holds the shared fileset
+ * reference.  A worker Tuplesortstate in leader is expected to do exactly the
+ * same amount of total initial processing work as a worker process
+ * Tuplesortstate, since the leader process has nothing else to do before
+ * workers finish.
+ *
+ * Note that only a very small amount of memory will be allocated prior to
+ * the leader state first consuming input, and that workers will free the
+ * vast majority of their memory upon returning from tuplesort_performsort().
+ * Callers can rely on this to arrange for memory to be used in a way that
+ * respects a workMem-style budget across an entire parallel sort operation.
+ *
+ * Callers are responsible for parallel safety in general.  However, they
+ * can at least rely on there being no parallel safety hazards within
+ * tuplesort, because tuplesort thinks of the sort as several independent
+ * sorts whose results are combined.  Since, in general, the behavior of
+ * sort operators is immutable, caller need only worry about the parallel
+ * safety of whatever the process is through which input tuples are
+ * generated (typically, caller uses a parallel heap scan).
+ */
+
+extern Tuplesortstate *tuplesort_begin_heap(TupleDesc tupDesc,
+											int nkeys, AttrNumber *attNums,
+											Oid *sortOperators, Oid *sortCollations,
+											bool *nullsFirstFlags,
+											int workMem, SortCoordinate coordinate,
+											bool randomAccess);
+extern Tuplesortstate *tuplesort_begin_cluster(TupleDesc tupDesc,
+											   Relation indexRel, int workMem,
+											   SortCoordinate coordinate, bool randomAccess);
+extern Tuplesortstate *tuplesort_begin_index_btree(Relation heapRel,
+												   Relation indexRel,
+												   bool enforceUnique,
+												   int workMem, SortCoordinate coordinate,
+												   bool randomAccess);
+extern Tuplesortstate *tuplesort_begin_index_hash(Relation heapRel,
+												  Relation indexRel,
+												  uint32 high_mask,
+												  uint32 low_mask,
+												  uint32 max_buckets,
+												  int workMem, SortCoordinate coordinate,
+												  bool randomAccess);
+extern Tuplesortstate *tuplesort_begin_datum(Oid datumType,
+											 Oid sortOperator, Oid sortCollation,
+											 bool nullsFirstFlag,
+											 int workMem, SortCoordinate coordinate,
+											 bool randomAccess);
+
+extern void tuplesort_set_bound(Tuplesortstate *state, int64 bound);
+extern bool tuplesort_used_bound(Tuplesortstate *state);
+
+extern void tuplesort_puttupleslot(Tuplesortstate *state,
+								   TupleTableSlot *slot);
+extern void tuplesort_putheaptuple(Tuplesortstate *state, HeapTuple tup);
+extern void tuplesort_putindextuplevalues(Tuplesortstate *state,
+										  Relation rel, ItemPointer self,
+										  Datum *values, bool *isnull);
+extern void tuplesort_putdatum(Tuplesortstate *state, Datum val,
+							   bool isNull);
+
+extern void tuplesort_performsort(Tuplesortstate *state);
+
+extern bool tuplesort_gettupleslot(Tuplesortstate *state, bool forward,
+								   bool copy, TupleTableSlot *slot, Datum *abbrev);
+extern HeapTuple tuplesort_getheaptuple(Tuplesortstate *state, bool forward);
+extern IndexTuple tuplesort_getindextuple(Tuplesortstate *state, bool forward);
+extern bool tuplesort_getdatum(Tuplesortstate *state, bool forward,
+							   Datum *val, bool *isNull, Datum *abbrev);
+
+extern bool tuplesort_skiptuples(Tuplesortstate *state, int64 ntuples,
+								 bool forward);
+
+extern void tuplesort_end(Tuplesortstate *state);
+
+extern void tuplesort_reset(Tuplesortstate *state);
+
+extern void tuplesort_get_stats(Tuplesortstate *state,
+								TuplesortInstrumentation *stats);
+extern const char *tuplesort_method_name(TuplesortMethod m);
+extern const char *tuplesort_space_type_name(TuplesortSpaceType t);
+
+extern int	tuplesort_merge_order(int64 allowedMem);
+
+extern Size tuplesort_estimate_shared(int nworkers);
+extern void tuplesort_initialize_shared(Sharedsort *shared, int nWorkers,
+										dsm_segment *seg);
+extern void tuplesort_attach_shared(Sharedsort *shared, dsm_segment *seg);
+
+/*
+ * These routines may only be called if randomAccess was specified 'true'.
+ * Likewise, backwards scan in gettuple/getdatum is only allowed if
+ * randomAccess was specified.  Note that parallel sorts do not support
+ * randomAccess.
+ */
+
+extern void tuplesort_rescan(Tuplesortstate *state);
+extern void tuplesort_markpos(Tuplesortstate *state);
+extern void tuplesort_restorepos(Tuplesortstate *state);
+
+#endif							/* TUPLESORT_H */