src/include/utils/tuplestore.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * tuplestore.h
   4  *        Generalized routines for temporary tuple storage.
   5  *
   6  * This module handles temporary storage of tuples for purposes such
   7  * as Materialize nodes, hashjoin batch files, etc.  It is essentially
   8  * a dumbed-down version of tuplesort.c; it does no sorting of tuples
   9  * but can only store and regurgitate a sequence of tuples.  However,
  10  * because no sort is required, it is allowed to start reading the sequence
  11  * before it has all been written.      This is particularly useful for cursors,
  12  * because it allows random access within the already-scanned portion of
  13  * a query without having to process the underlying scan to completion.
  14  * Also, it is possible to support multiple independent read pointers.
  15  *
  16  * A temporary file is used to handle the data if it exceeds the
  17  * space limit specified by the caller.
  18  *
  19  * Beginning in Postgres 8.2, what is stored is just MinimalTuples;
  20  * callers cannot expect valid system columns in regurgitated tuples.
  21  * Also, we have changed the API to return tuples in TupleTableSlots,
  22  * so that there is a check to prevent attempted access to system columns.
  23  *
  24  * Portions Copyright (c) 1996-2009, PostgreSQL Global Development Group
  25  * Portions Copyright (c) 1994, Regents of the University of California
  26  *
  27  * $PostgreSQL$
  28  *
  29  *-------------------------------------------------------------------------
  30  */
  31 #ifndef TUPLESTORE_H
  32 #define TUPLESTORE_H
  33
  34 #include "executor/tuptable.h"
  35
  36
  37 /* Tuplestorestate is an opaque type whose details are not known outside
  38  * tuplestore.c.
  39  */
  40 typedef struct Tuplestorestate Tuplestorestate;
  41
  42 /*
  43  * Currently we only need to store MinimalTuples, but it would be easy
  44  * to support the same behavior for IndexTuples and/or bare Datums.
  45  */
  46
  47 extern Tuplestorestate *tuplestore_begin_heap(bool randomAccess,
  48                                           bool interXact,
  49                                           int maxKBytes);
  50
  51 extern void tuplestore_set_eflags(Tuplestorestate *state, int eflags);
  52
  53 extern void tuplestore_puttupleslot(Tuplestorestate *state,
  54                                                 TupleTableSlot *slot);
  55 extern void tuplestore_puttuple(Tuplestorestate *state, HeapTuple tuple);
  56 extern void tuplestore_putvalues(Tuplestorestate *state, TupleDesc tdesc,
  57                                          Datum *values, bool *isnull);
  58
  59 /* tuplestore_donestoring() used to be required, but is no longer used */
  60 #define tuplestore_donestoring(state)   ((void) 0)
  61
  62 extern int      tuplestore_alloc_read_pointer(Tuplestorestate *state, int eflags);
  63
  64 extern void tuplestore_select_read_pointer(Tuplestorestate *state, int ptr);
  65
  66 extern void tuplestore_copy_read_pointer(Tuplestorestate *state,
  67                                                          int srcptr, int destptr);
  68
  69 extern void tuplestore_trim(Tuplestorestate *state);
  70
  71 extern bool tuplestore_in_memory(Tuplestorestate *state);
  72
  73 extern bool tuplestore_gettupleslot(Tuplestorestate *state, bool forward,
  74                                                 bool copy, TupleTableSlot *slot);
  75 extern bool tuplestore_advance(Tuplestorestate *state, bool forward);
  76
  77 extern bool tuplestore_ateof(Tuplestorestate *state);
  78
  79 extern void tuplestore_rescan(Tuplestorestate *state);
  80
  81 extern void tuplestore_clear(Tuplestorestate *state);
  82
  83 extern void tuplestore_end(Tuplestorestate *state);
  84
  85 #endif   /* TUPLESTORE_H */