src/include/storage/read_stream.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * read_stream.h
   4  *        Mechanism for accessing buffered relation data with look-ahead
   5  *
   6  *
   7  * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
   8  * Portions Copyright (c) 1994, Regents of the University of California
   9  *
  10  * src/include/storage/read_stream.h
  11  *
  12  *-------------------------------------------------------------------------
  13  */
  14 #ifndef READ_STREAM_H
  15 #define READ_STREAM_H
  16
  17 #include "storage/bufmgr.h"
  18 #include "storage/smgr.h"
  19
  20 /* Default tuning, reasonable for many users. */
  21 #define READ_STREAM_DEFAULT 0x00
  22
  23 /*
  24  * I/O streams that are performing maintenance work on behalf of potentially
  25  * many users, and thus should be governed by maintenance_io_concurrency
  26  * instead of effective_io_concurrency.  For example, VACUUM or CREATE INDEX.
  27  */
  28 #define READ_STREAM_MAINTENANCE 0x01
  29
  30 /*
  31  * We usually avoid issuing prefetch advice automatically when sequential
  32  * access is detected, but this flag explicitly disables it, for cases that
  33  * might not be correctly detected.  Explicit advice is known to perform worse
  34  * than letting the kernel (at least Linux) detect sequential access.
  35  */
  36 #define READ_STREAM_SEQUENTIAL 0x02
  37
  38 /*
  39  * We usually ramp up from smaller reads to larger ones, to support users who
  40  * don't know if it's worth reading lots of buffers yet.  This flag disables
  41  * that, declaring ahead of time that we'll be reading all available buffers.
  42  */
  43 #define READ_STREAM_FULL 0x04
  44
  45 struct ReadStream;
  46 typedef struct ReadStream ReadStream;
  47
  48 /* for block_range_read_stream_cb */
  49 typedef struct BlockRangeReadStreamPrivate
  50 {
  51         BlockNumber current_blocknum;
  52         BlockNumber last_exclusive;
  53 } BlockRangeReadStreamPrivate;
  54
  55 /* Callback that returns the next block number to read. */
  56 typedef BlockNumber (*ReadStreamBlockNumberCB) (ReadStream *stream,
  57                                                                                                 void *callback_private_data,
  58                                                                                                 void *per_buffer_data);
  59
  60 extern BlockNumber block_range_read_stream_cb(ReadStream *stream,
  61                                                                                           void *callback_private_data,
  62                                                                                           void *per_buffer_data);
  63 extern ReadStream *read_stream_begin_relation(int flags,
  64                                                                                           BufferAccessStrategy strategy,
  65                                                                                           Relation rel,
  66                                                                                           ForkNumber forknum,
  67                                                                                           ReadStreamBlockNumberCB callback,
  68                                                                                           void *callback_private_data,
  69                                                                                           size_t per_buffer_data_size);
  70 extern Buffer read_stream_next_buffer(ReadStream *stream, void **per_buffer_data);
  71 extern BlockNumber read_stream_next_block(ReadStream *stream,
  72                                                                                   BufferAccessStrategy *strategy);
  73 extern ReadStream *read_stream_begin_smgr_relation(int flags,
  74                                                                                                    BufferAccessStrategy strategy,
  75                                                                                                    SMgrRelation smgr,
  76                                                                                                    char smgr_persistence,
  77                                                                                                    ForkNumber forknum,
  78                                                                                                    ReadStreamBlockNumberCB callback,
  79                                                                                                    void *callback_private_data,
  80                                                                                                    size_t per_buffer_data_size);
  81 extern void read_stream_reset(ReadStream *stream);
  82 extern void read_stream_end(ReadStream *stream);
  83
  84 #endif                                                  /* READ_STREAM_H */