src/include/utils/logtape.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * logtape.h
   4  *        Management of "logical tapes" within temporary files.
   5  *
   6  * See logtape.c for explanations.
   7  *
   8  * Portions Copyright (c) 1996-2022, PostgreSQL Global Development Group
   9  * Portions Copyright (c) 1994, Regents of the University of California
  10  *
  11  * src/include/utils/logtape.h
  12  *
  13  *-------------------------------------------------------------------------
  14  */
  15
  16 #ifndef LOGTAPE_H
  17 #define LOGTAPE_H
  18
  19 #include "storage/sharedfileset.h"
  20
  21 /*
  22  * LogicalTapeSet and LogicalTape are opaque types whose details are not
  23  * known outside logtape.c.
  24  */
  25 typedef struct LogicalTapeSet LogicalTapeSet;
  26 typedef struct LogicalTape LogicalTape;
  27
  28
  29 /*
  30  * The approach tuplesort.c takes to parallel external sorts is that workers,
  31  * whose state is almost the same as independent serial sorts, are made to
  32  * produce a final materialized tape of sorted output in all cases.  This is
  33  * frozen, just like any case requiring a final materialized tape.  However,
  34  * there is one difference, which is that freezing will also export an
  35  * underlying shared fileset BufFile for sharing.  Freezing produces TapeShare
  36  * metadata for the worker when this happens, which is passed along through
  37  * shared memory to leader.
  38  *
  39  * The leader process can then pass an array of TapeShare metadata (one per
  40  * worker participant) to LogicalTapeSetCreate(), alongside a handle to a
  41  * shared fileset, which is sufficient to construct a new logical tapeset that
  42  * consists of each of the tapes materialized by workers.
  43  *
  44  * Note that while logtape.c does create an empty leader tape at the end of the
  45  * tapeset in the leader case, it can never be written to due to a restriction
  46  * in the shared buffile infrastructure.
  47  */
  48 typedef struct TapeShare
  49 {
  50         /*
  51          * Currently, all the leader process needs is the location of the
  52          * materialized tape's first block.
  53          */
  54         long            firstblocknumber;
  55 } TapeShare;
  56
  57 /*
  58  * prototypes for functions in logtape.c
  59  */
  60
  61 extern LogicalTapeSet *LogicalTapeSetCreate(bool preallocate,
  62                                                                                         SharedFileSet *fileset, int worker);
  63 extern void LogicalTapeClose(LogicalTape *lt);
  64 extern void LogicalTapeSetClose(LogicalTapeSet *lts);
  65 extern LogicalTape *LogicalTapeCreate(LogicalTapeSet *lts);
  66 extern LogicalTape *LogicalTapeImport(LogicalTapeSet *lts, int worker, TapeShare *shared);
  67 extern void LogicalTapeSetForgetFreeSpace(LogicalTapeSet *lts);
  68 extern size_t LogicalTapeRead(LogicalTape *lt, void *ptr, size_t size);
  69 extern void LogicalTapeWrite(LogicalTape *lt, void *ptr, size_t size);
  70 extern void LogicalTapeRewindForRead(LogicalTape *lt, size_t buffer_size);
  71 extern void LogicalTapeFreeze(LogicalTape *lt, TapeShare *share);
  72 extern size_t LogicalTapeBackspace(LogicalTape *lt, size_t size);
  73 extern void LogicalTapeSeek(LogicalTape *lt, long blocknum, int offset);
  74 extern void LogicalTapeTell(LogicalTape *lt, long *blocknum, int *offset);
  75 extern long LogicalTapeSetBlocks(LogicalTapeSet *lts);
  76
  77 #endif                                                  /* LOGTAPE_H */