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-2021, 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         BlockNumber bt_blkno;           /* heap blkno that the tuple is for */
  48         MemoryContext bt_context;       /* memcxt holding the bt_columns values */
  49         /* output arrays for brin_deform_tuple: */
  50         Datum      *bt_values;          /* values array */
  51         bool       *bt_allnulls;        /* allnulls array */
  52         bool       *bt_hasnulls;        /* hasnulls array */
  53         /* not an output array, but must be last */
  54         BrinValues      bt_columns[FLEXIBLE_ARRAY_MEMBER];
  55 } BrinMemTuple;
  56
  57 /*
  58  * An on-disk BRIN tuple.  This is possibly followed by a nulls bitmask, with
  59  * room for 2 null bits (two bits for each indexed column); an opclass-defined
  60  * number of Datum values for each column follow.
  61  */
  62 typedef struct BrinTuple
  63 {
  64         /* heap block number that the tuple is for */
  65         BlockNumber bt_blkno;
  66
  67         /* ---------------
  68          * bt_info is laid out in the following fashion:
  69          *
  70          * 7th (high) bit: has nulls
  71          * 6th bit: is placeholder tuple
  72          * 5th bit: unused
  73          * 4-0 bit: offset of data
  74          * ---------------
  75          */
  76         uint8           bt_info;
  77 } BrinTuple;
  78
  79 #define SizeOfBrinTuple (offsetof(BrinTuple, bt_info) + sizeof(uint8))
  80
  81 /*
  82  * bt_info manipulation macros
  83  */
  84 #define BRIN_OFFSET_MASK                0x1F
  85 /* bit 0x20 is not used at present */
  86 #define BRIN_PLACEHOLDER_MASK   0x40
  87 #define BRIN_NULLS_MASK                 0x80
  88
  89 #define BrinTupleDataOffset(tup)        ((Size) (((BrinTuple *) (tup))->bt_info & BRIN_OFFSET_MASK))
  90 #define BrinTupleHasNulls(tup)  (((((BrinTuple *) (tup))->bt_info & BRIN_NULLS_MASK)) != 0)
  91 #define BrinTupleIsPlaceholder(tup) (((((BrinTuple *) (tup))->bt_info & BRIN_PLACEHOLDER_MASK)) != 0)
  92
  93
  94 extern BrinTuple *brin_form_tuple(BrinDesc *brdesc, BlockNumber blkno,
  95                                                                   BrinMemTuple *tuple, Size *size);
  96 extern BrinTuple *brin_form_placeholder_tuple(BrinDesc *brdesc,
  97                                                                                           BlockNumber blkno, Size *size);
  98 extern void brin_free_tuple(BrinTuple *tuple);
  99 extern BrinTuple *brin_copy_tuple(BrinTuple *tuple, Size len,
 100                                                                   BrinTuple *dest, Size *destsz);
 101 extern bool brin_tuples_equal(const BrinTuple *a, Size alen,
 102                                                           const BrinTuple *b, Size blen);
 103
 104 extern BrinMemTuple *brin_new_memtuple(BrinDesc *brdesc);
 105 extern BrinMemTuple *brin_memtuple_initialize(BrinMemTuple *dtuple,
 106                                                                                           BrinDesc *brdesc);
 107 extern BrinMemTuple *brin_deform_tuple(BrinDesc *brdesc,
 108                                                                            BrinTuple *tuple, BrinMemTuple *dMemtuple);
 109
 110 #endif                                                  /* BRIN_TUPLE_H */