1 /*-------------------------------------------------------------------------
4 * Generalized tuple sorting routines.
6 * This module handles sorting of heap tuples, index tuples, or single
7 * Datums (and could easily support other kinds of sortable objects,
8 * if necessary). It works efficiently for both small and large amounts
9 * of data. Small amounts are sorted in-memory using qsort(). Large
10 * amounts are sorted using temporary files and a standard external sort
13 * Portions Copyright (c) 1996-2006, PostgreSQL Global Development Group
14 * Portions Copyright (c) 1994, Regents of the University of California
16 * $PostgreSQL: pgsql/src/include/utils/tuplesort.h,v 1.20 2006/05/23 21:37:59 tgl Exp $
18 *-------------------------------------------------------------------------
23 #include "access/htup.h"
24 #include "access/itup.h"
27 /* Tuplesortstate is an opaque type whose details are not known outside tuplesort.c. */
29 typedef struct Tuplesortstate Tuplesortstate;
32 * We provide two different interfaces to what is essentially the same
33 * code: one for sorting HeapTuples and one for sorting IndexTuples.
34 * They differ primarily in the way that the sort key information is
35 * supplied. Also, tuplesort.c guarantees to preserve all the header
36 * fields of an IndexTuple, but when sorting HeapTuples only the user data
37 * is guaranteed preserved, not the "system columns" (tuple identity and
38 * transaction visibility info).
40 * Yet a third slightly different interface supports sorting bare Datums.
43 extern Tuplesortstate *tuplesort_begin_heap(TupleDesc tupDesc,
45 Oid *sortOperators, AttrNumber *attNums,
46 int workMem, bool randomAccess);
47 extern Tuplesortstate *tuplesort_begin_index(Relation indexRel,
49 int workMem, bool randomAccess);
50 extern Tuplesortstate *tuplesort_begin_datum(Oid datumType,
52 int workMem, bool randomAccess);
54 extern void tuplesort_puttuple(Tuplesortstate *state, void *tuple);
56 extern void tuplesort_putdatum(Tuplesortstate *state, Datum val,
59 extern void tuplesort_performsort(Tuplesortstate *state);
61 extern void *tuplesort_gettuple(Tuplesortstate *state, bool forward,
64 #define tuplesort_getheaptuple(state, forward, should_free) \
65 ((HeapTuple) tuplesort_gettuple(state, forward, should_free))
66 #define tuplesort_getindextuple(state, forward, should_free) \
67 ((IndexTuple) tuplesort_gettuple(state, forward, should_free))
69 extern bool tuplesort_getdatum(Tuplesortstate *state, bool forward,
70 Datum *val, bool *isNull);
72 extern void tuplesort_end(Tuplesortstate *state);
74 extern int tuplesort_merge_order(long allowedMem);
77 * These routines may only be called if randomAccess was specified 'true'.
78 * Likewise, backwards scan in gettuple/getdatum is only allowed if
79 * randomAccess was specified.
82 extern void tuplesort_rescan(Tuplesortstate *state);
83 extern void tuplesort_markpos(Tuplesortstate *state);
84 extern void tuplesort_restorepos(Tuplesortstate *state);
87 * This routine selects an appropriate sorting function to implement
88 * a sort operator as efficiently as possible.
92 SORTFUNC_LT, /* raw "<" operator */
93 SORTFUNC_REVLT, /* raw "<" operator, but reverse NULLs */
94 SORTFUNC_CMP, /* -1 / 0 / 1 three-way comparator */
95 SORTFUNC_REVCMP /* 1 / 0 / -1 (reversed) 3-way comparator */
98 extern void SelectSortFunction(Oid sortOperator,
99 RegProcedure *sortFunction,
100 SortFunctionKind *kind);
103 * Apply a sort function (by now converted to fmgr lookup form)
104 * and return a 3-way comparison result. This takes care of handling
105 * NULLs and sort ordering direction properly.
107 extern int32 ApplySortFunction(FmgrInfo *sortFunction, SortFunctionKind kind,
108 Datum datum1, bool isNull1,
109 Datum datum2, bool isNull2);
111 #endif /* TUPLESORT_H */