granicus.if.org Git - postgresql/blob - src/include/utils/tuplesort.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * tuplesort.h
   4  *        Generalized tuple sorting routines.
   5  *
   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
  11  * algorithm.
  12  *
  13  * Portions Copyright (c) 1996-2008, PostgreSQL Global Development Group
  14  * Portions Copyright (c) 1994, Regents of the University of California
  15  *
  16  * $PostgreSQL: pgsql/src/include/utils/tuplesort.h,v 1.28 2008/01/01 19:45:59 momjian Exp $
  17  *
  18  *-------------------------------------------------------------------------
  19  */
  20 #ifndef TUPLESORT_H
  21 #define TUPLESORT_H
  22
  23 #include "access/itup.h"
  24 #include "executor/tuptable.h"
  25
  26
  27 /* Tuplesortstate is an opaque type whose details are not known outside
  28  * tuplesort.c.
  29  */
  30 typedef struct Tuplesortstate Tuplesortstate;
  31
  32 /*
  33  * We provide two different interfaces to what is essentially the same
  34  * code: one for sorting HeapTuples and one for sorting IndexTuples.
  35  * They differ primarily in the way that the sort key information is
  36  * supplied.  Also, the HeapTuple case actually stores MinimalTuples,
  37  * which means it doesn't preserve the "system columns" (tuple identity and
  38  * transaction visibility info).  The IndexTuple case does preserve all
  39  * the header fields of an index entry.  In the HeapTuple case we can
  40  * save some cycles by passing and returning the tuples in TupleTableSlots,
  41  * rather than forming actual HeapTuples (which'd have to be converted to
  42  * MinimalTuples).
  43  *
  44  * Yet a third slightly different interface supports sorting bare Datums.
  45  */
  46
  47 extern Tuplesortstate *tuplesort_begin_heap(TupleDesc tupDesc,
  48                                          int nkeys, AttrNumber *attNums,
  49                                          Oid *sortOperators, bool *nullsFirstFlags,
  50                                          int workMem, bool randomAccess);
  51 extern Tuplesortstate *tuplesort_begin_index(Relation indexRel,
  52                                           bool enforceUnique,
  53                                           int workMem, bool randomAccess);
  54 extern Tuplesortstate *tuplesort_begin_datum(Oid datumType,
  55                                           Oid sortOperator, bool nullsFirstFlag,
  56                                           int workMem, bool randomAccess);
  57
  58 extern void tuplesort_set_bound(Tuplesortstate *state, int64 bound);
  59
  60 extern void tuplesort_puttupleslot(Tuplesortstate *state,
  61                                            TupleTableSlot *slot);
  62 extern void tuplesort_putindextuple(Tuplesortstate *state, IndexTuple tuple);
  63 extern void tuplesort_putdatum(Tuplesortstate *state, Datum val,
  64                                    bool isNull);
  65
  66 extern void tuplesort_performsort(Tuplesortstate *state);
  67
  68 extern bool tuplesort_gettupleslot(Tuplesortstate *state, bool forward,
  69                                            TupleTableSlot *slot);
  70 extern IndexTuple tuplesort_getindextuple(Tuplesortstate *state, bool forward,
  71                                                 bool *should_free);
  72 extern bool tuplesort_getdatum(Tuplesortstate *state, bool forward,
  73                                    Datum *val, bool *isNull);
  74
  75 extern void tuplesort_end(Tuplesortstate *state);
  76
  77 extern char *tuplesort_explain(Tuplesortstate *state);
  78
  79 extern int      tuplesort_merge_order(long allowedMem);
  80
  81 /*
  82  * These routines may only be called if randomAccess was specified 'true'.
  83  * Likewise, backwards scan in gettuple/getdatum is only allowed if
  84  * randomAccess was specified.
  85  */
  86
  87 extern void tuplesort_rescan(Tuplesortstate *state);
  88 extern void tuplesort_markpos(Tuplesortstate *state);
  89 extern void tuplesort_restorepos(Tuplesortstate *state);
  90
  91 /* Setup for ApplySortFunction */
  92 extern void SelectSortFunction(Oid sortOperator, bool nulls_first,
  93                                    Oid *sortFunction,
  94                                    int *sortFlags);
  95
  96 /*
  97  * Apply a sort function (by now converted to fmgr lookup form)
  98  * and return a 3-way comparison result.  This takes care of handling
  99  * reverse-sort and NULLs-ordering properly.
 100  */
 101 extern int32 ApplySortFunction(FmgrInfo *sortFunction, int sortFlags,
 102                                   Datum datum1, bool isNull1,
 103                                   Datum datum2, bool isNull2);
 104
 105 #endif   /* TUPLESORT_H */