* amounts are sorted using temporary files and a standard external sort
* algorithm.
*
- * Portions Copyright (c) 1996-2000, PostgreSQL, Inc
+ * Portions Copyright (c) 1996-2011, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
- * $Id: tuplesort.h,v 1.4 2000/04/12 17:16:56 momjian Exp $
+ * src/include/utils/tuplesort.h
*
*-------------------------------------------------------------------------
*/
#ifndef TUPLESORT_H
#define TUPLESORT_H
-#include "access/htup.h"
#include "access/itup.h"
-#include "access/skey.h"
-#include "access/tupdesc.h"
-#include "utils/rel.h"
+#include "executor/tuptable.h"
+#include "fmgr.h"
+#include "utils/relcache.h"
-/* Tuplesortstate is an opaque type whose details are not known outside tuplesort.c. */
+/* Tuplesortstate is an opaque type whose details are not known outside
+ * tuplesort.c.
+ */
typedef struct Tuplesortstate Tuplesortstate;
/*
- * We provide two different interfaces to what is essentially the same
- * code: one for sorting HeapTuples and one for sorting IndexTuples.
- * They differ primarily in the way that the sort key information is
- * supplied.
- * Yet a third slightly different interface supports sorting bare Datums.
+ * 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.
+ *
+ * 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.
*/
extern Tuplesortstate *tuplesort_begin_heap(TupleDesc tupDesc,
- int nkeys, ScanKey keys,
- bool randomAccess);
-extern Tuplesortstate *tuplesort_begin_index(Relation indexRel,
- bool enforceUnique,
- bool randomAccess);
+ int nkeys, AttrNumber *attNums,
+ Oid *sortOperators, Oid *sortCollations,
+ bool *nullsFirstFlags,
+ int workMem, bool randomAccess);
+extern Tuplesortstate *tuplesort_begin_cluster(TupleDesc tupDesc,
+ Relation indexRel,
+ int workMem, bool randomAccess);
+extern Tuplesortstate *tuplesort_begin_index_btree(Relation indexRel,
+ bool enforceUnique,
+ int workMem, bool randomAccess);
+extern Tuplesortstate *tuplesort_begin_index_hash(Relation indexRel,
+ uint32 hash_mask,
+ int workMem, bool randomAccess);
extern Tuplesortstate *tuplesort_begin_datum(Oid datumType,
- Oid sortOperator,
- bool randomAccess);
+ Oid sortOperator, Oid sortCollation,
+ bool nullsFirstFlag,
+ int workMem, bool randomAccess);
-extern void tuplesort_puttuple(Tuplesortstate *state, void *tuple);
+extern void tuplesort_set_bound(Tuplesortstate *state, int64 bound);
+extern void tuplesort_puttupleslot(Tuplesortstate *state,
+ TupleTableSlot *slot);
+extern void tuplesort_putheaptuple(Tuplesortstate *state, HeapTuple tup);
+extern void tuplesort_putindextuple(Tuplesortstate *state, IndexTuple tuple);
extern void tuplesort_putdatum(Tuplesortstate *state, Datum val,
bool isNull);
extern void tuplesort_performsort(Tuplesortstate *state);
-extern void *tuplesort_gettuple(Tuplesortstate *state, bool forward,
- bool *should_free);
-
-#define tuplesort_getheaptuple(state, forward, should_free) \
- ((HeapTuple) tuplesort_gettuple(state, forward, should_free))
-#define tuplesort_getindextuple(state, forward, should_free) \
- ((IndexTuple) tuplesort_gettuple(state, forward, should_free))
-
+extern bool tuplesort_gettupleslot(Tuplesortstate *state, bool forward,
+ TupleTableSlot *slot);
+extern HeapTuple tuplesort_getheaptuple(Tuplesortstate *state, bool forward,
+ bool *should_free);
+extern IndexTuple tuplesort_getindextuple(Tuplesortstate *state, bool forward,
+ bool *should_free);
extern bool tuplesort_getdatum(Tuplesortstate *state, bool forward,
Datum *val, bool *isNull);
extern void tuplesort_end(Tuplesortstate *state);
+extern void tuplesort_get_stats(Tuplesortstate *state,
+ const char **sortMethod,
+ const char **spaceType,
+ long *spaceUsed);
+
+extern int tuplesort_merge_order(long allowedMem);
+
/*
* These routines may only be called if randomAccess was specified 'true'.
* Likewise, backwards scan in gettuple/getdatum is only allowed if
extern void tuplesort_markpos(Tuplesortstate *state);
extern void tuplesort_restorepos(Tuplesortstate *state);
-#endif /* TUPLESORT_H */
+#endif /* TUPLESORT_H */