src/include/access/brin_tuple.h

   1 /*
   2  * brin_tuple.h
   3  *              Declarations for dealing with BRIN-specific tuples.
   4  *
   5  * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
   6  * Portions Copyright (c) 1994, Regents of the University of California
   7  *
   8  * IDENTIFICATION
   9  *        src/include/access/brin_tuple.h
  10  */
  11 #ifndef BRIN_TUPLE_H
  12 #define BRIN_TUPLE_H
  13
  14 #include "access/brin_internal.h"
  15 #include "access/tupdesc.h"
  16
  17 /*
  18  * The BRIN opclasses may register serialization callback, in case the on-disk
  19  * and in-memory representations differ (e.g. for performance reasons).
  20  */
  21 typedef void (*brin_serialize_callback_type) (BrinDesc *bdesc, Datum src, Datum *dst);
  22
  23 /*
  24  * A BRIN index stores one index tuple per page range.  Each index tuple
  25  * has one BrinValues struct for each indexed column; in turn, each BrinValues
  26  * has (besides the null flags) an array of Datum whose size is determined by
  27  * the opclass.
  28  */
  29 typedef struct BrinValues
  30 {
  31         AttrNumber      bv_attno;               /* index attribute number */
  32         bool            bv_hasnulls;    /* are there any nulls in the page range? */
  33         bool            bv_allnulls;    /* are all values nulls in the page range? */
  34         Datum      *bv_values;          /* current accumulated values */
  35         Datum           bv_mem_value;   /* expanded accumulated values */
  36         MemoryContext bv_context;
  37         brin_serialize_callback_type bv_serialize;
  38 } BrinValues;
  39
  40 /*
  41  * This struct is used to represent an in-memory index tuple.  The values can
  42  * only be meaningfully decoded with an appropriate BrinDesc.
  43  */
  44 typedef struct BrinMemTuple
  45 {
  46         bool            bt_placeholder; /* this is a placeholder tuple */
  47         bool            bt_empty_range; /* range represents no tuples */
  48         BlockNumber bt_blkno;           /* heap blkno that the tuple is for */
  49         MemoryContext bt_context;       /* memcxt holding the bt_columns values */
  50         /* output arrays for brin_deform_tuple: */
  51         Datum      *bt_values;          /* values array */
  52         bool       *bt_allnulls;        /* allnulls array */
  53         bool       *bt_hasnulls;        /* hasnulls array */
  54         /* not an output array, but must be last */
  55         BrinValues      bt_columns[FLEXIBLE_ARRAY_MEMBER];
  56 } BrinMemTuple;
  57
  58 /*
  59  * An on-disk BRIN tuple.  This is possibly followed by a nulls bitmask, with
  60  * room for 2 null bits (two bits for each indexed column); an opclass-defined
  61  * number of Datum values for each column follow.
  62  */
  63 typedef struct BrinTuple
  64 {
  65         /* heap block number that the tuple is for */
  66         BlockNumber bt_blkno;
  67
  68         /* ---------------
  69          * bt_info is laid out in the following fashion:
  70          *
  71          * 7th (high) bit: has nulls
  72          * 6th bit: is placeholder tuple
  73          * 5th bit: range is empty
  74          * 4-0 bit: offset of data
  75          * ---------------
  76          */
  77         uint8           bt_info;
  78 } BrinTuple;
  79
  80 #define SizeOfBrinTuple (offsetof(BrinTuple, bt_info) + sizeof(uint8))
  81
  82 /*
  83  * bt_info manipulation macros
  84  */
  85 #define BRIN_OFFSET_MASK                0x1F
  86 #define BRIN_EMPTY_RANGE_MASK   0x20
  87 #define BRIN_PLACEHOLDER_MASK   0x40
  88 #define BRIN_NULLS_MASK                 0x80
  89
  90 #define BrinTupleDataOffset(tup)        ((Size) (((BrinTuple *) (tup))->bt_info & BRIN_OFFSET_MASK))
  91 #define BrinTupleHasNulls(tup)  (((((BrinTuple *) (tup))->bt_info & BRIN_NULLS_MASK)) != 0)
  92 #define BrinTupleIsPlaceholder(tup) (((((BrinTuple *) (tup))->bt_info & BRIN_PLACEHOLDER_MASK)) != 0)
  93 #define BrinTupleIsEmptyRange(tup) (((((BrinTuple *) (tup))->bt_info & BRIN_EMPTY_RANGE_MASK)) != 0)
  94
  95
  96 extern BrinTuple *brin_form_tuple(BrinDesc *brdesc, BlockNumber blkno,
  97                                                                   BrinMemTuple *tuple, Size *size);
  98 extern BrinTuple *brin_form_placeholder_tuple(BrinDesc *brdesc,
  99                                                                                           BlockNumber blkno, Size *size);
 100 extern void brin_free_tuple(BrinTuple *tuple);
 101 extern BrinTuple *brin_copy_tuple(BrinTuple *tuple, Size len,
 102                                                                   BrinTuple *dest, Size *destsz);
 103 extern bool brin_tuples_equal(const BrinTuple *a, Size alen,
 104                                                           const BrinTuple *b, Size blen);
 105
 106 extern BrinMemTuple *brin_new_memtuple(BrinDesc *brdesc);
 107 extern BrinMemTuple *brin_memtuple_initialize(BrinMemTuple *dtuple,
 108                                                                                           BrinDesc *brdesc);
 109 extern BrinMemTuple *brin_deform_tuple(BrinDesc *brdesc,
 110                                                                            BrinTuple *tuple, BrinMemTuple *dMemtuple);
 111
 112 #endif                                                  /* BRIN_TUPLE_H */