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-2001, PostgreSQL Global Development Group
  14  * Portions Copyright (c) 1994, Regents of the University of California
  15  *
  16  * $Id: tuplesort.h,v 1.10 2001/10/28 06:26:10 momjian Exp $
  17  *
  18  *-------------------------------------------------------------------------
  19  */
  20 #ifndef TUPLESORT_H
  21 #define TUPLESORT_H
  22
  23 #include "access/htup.h"
  24 #include "access/itup.h"
  25 #include "fmgr.h"
  26
  27 /* Tuplesortstate is an opaque type whose details are not known outside tuplesort.c. */
  28
  29 typedef struct Tuplesortstate Tuplesortstate;
  30
  31 /*
  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.
  36  * Yet a third slightly different interface supports sorting bare Datums.
  37  */
  38
  39 extern Tuplesortstate *tuplesort_begin_heap(TupleDesc tupDesc,
  40                                          int nkeys,
  41                                          Oid *sortOperators, AttrNumber *attNums,
  42                                          bool randomAccess);
  43 extern Tuplesortstate *tuplesort_begin_index(Relation indexRel,
  44                                           bool enforceUnique,
  45                                           bool randomAccess);
  46 extern Tuplesortstate *tuplesort_begin_datum(Oid datumType,
  47                                           Oid sortOperator,
  48                                           bool randomAccess);
  49
  50 extern void tuplesort_puttuple(Tuplesortstate *state, void *tuple);
  51
  52 extern void tuplesort_putdatum(Tuplesortstate *state, Datum val,
  53                                    bool isNull);
  54
  55 extern void tuplesort_performsort(Tuplesortstate *state);
  56
  57 extern void *tuplesort_gettuple(Tuplesortstate *state, bool forward,
  58                                    bool *should_free);
  59
  60 #define tuplesort_getheaptuple(state, forward, should_free) \
  61         ((HeapTuple) tuplesort_gettuple(state, forward, should_free))
  62 #define tuplesort_getindextuple(state, forward, should_free) \
  63         ((IndexTuple) tuplesort_gettuple(state, forward, should_free))
  64
  65 extern bool tuplesort_getdatum(Tuplesortstate *state, bool forward,
  66                                    Datum *val, bool *isNull);
  67
  68 extern void tuplesort_end(Tuplesortstate *state);
  69
  70 /*
  71  * These routines may only be called if randomAccess was specified 'true'.
  72  * Likewise, backwards scan in gettuple/getdatum is only allowed if
  73  * randomAccess was specified.
  74  */
  75
  76 extern void tuplesort_rescan(Tuplesortstate *state);
  77 extern void tuplesort_markpos(Tuplesortstate *state);
  78 extern void tuplesort_restorepos(Tuplesortstate *state);
  79
  80 /*
  81  * This routine selects an appropriate sorting function to implement
  82  * a sort operator as efficiently as possible.
  83  */
  84 typedef enum
  85 {
  86         SORTFUNC_LT,                            /* raw "<" operator */
  87         SORTFUNC_REVLT,                         /* raw "<" operator, but reverse NULLs */
  88         SORTFUNC_CMP,                           /* -1 / 0 / 1 three-way comparator */
  89         SORTFUNC_REVCMP                         /* 1 / 0 / -1 (reversed) 3-way comparator */
  90 } SortFunctionKind;
  91
  92 extern void SelectSortFunction(Oid sortOperator,
  93                                    RegProcedure *sortFunction,
  94                                    SortFunctionKind *kind);
  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  * NULLs and sort ordering direction properly.
 100  */
 101 extern int32 ApplySortFunction(FmgrInfo *sortFunction, SortFunctionKind kind,
 102                                   Datum datum1, bool isNull1,
 103                                   Datum datum2, bool isNull2);
 104
 105 #endif   /* TUPLESORT_H */