src/include/access/toast_helper.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * toast_helper.h
   4  *        Helper functions for table AMs implementing compressed or
   5  *    out-of-line storage of varlena attributes.
   6  *
   7  * Copyright (c) 2000-2021, PostgreSQL Global Development Group
   8  *
   9  * src/include/access/toast_helper.h
  10  *
  11  *-------------------------------------------------------------------------
  12  */
  13
  14 #ifndef TOAST_HELPER_H
  15 #define TOAST_HELPER_H
  16
  17 #include "utils/rel.h"
  18
  19 /*
  20  * Information about one column of a tuple being toasted.
  21  *
  22  * NOTE: toast_action[i] can have these values:
  23  *              ' '                                             default handling
  24  *              TYPSTORAGE_PLAIN                already processed --- don't touch it
  25  *              TYPSTORAGE_EXTENDED             incompressible, but OK to move off
  26  *
  27  * NOTE: toast_attr[i].tai_size is only made valid for varlena attributes with
  28  * toast_action[i] different from TYPSTORAGE_PLAIN.
  29  */
  30 typedef struct
  31 {
  32         struct varlena *tai_oldexternal;
  33         int32           tai_size;
  34         uint8           tai_colflags;
  35         char            tai_compression;
  36 } ToastAttrInfo;
  37
  38 /*
  39  * Information about one tuple being toasted.
  40  */
  41 typedef struct
  42 {
  43         /*
  44          * Before calling toast_tuple_init, the caller must initialize the
  45          * following fields.  Each array must have a length equal to
  46          * ttc_rel->rd_att->natts.  The tts_oldvalues and tts_oldisnull fields
  47          * should be NULL in the case of an insert.
  48          */
  49         Relation        ttc_rel;                /* the relation that contains the tuple */
  50         Datum      *ttc_values;         /* values from the tuple columns */
  51         bool       *ttc_isnull;         /* null flags for the tuple columns */
  52         Datum      *ttc_oldvalues;      /* values from previous tuple */
  53         bool       *ttc_oldisnull;      /* null flags from previous tuple */
  54
  55         /*
  56          * Before calling toast_tuple_init, the caller should set tts_attr to
  57          * point to an array of ToastAttrInfo structures of a length equal to
  58          * tts_rel->rd_att->natts.  The contents of the array need not be
  59          * initialized.  ttc_flags also does not need to be initialized.
  60          */
  61         uint8           ttc_flags;
  62         ToastAttrInfo *ttc_attr;
  63 } ToastTupleContext;
  64
  65 /*
  66  * Flags indicating the overall state of a TOAST operation.
  67  *
  68  * TOAST_NEEDS_DELETE_OLD indicates that one or more old TOAST datums need
  69  * to be deleted.
  70  *
  71  * TOAST_NEEDS_FREE indicates that one or more TOAST values need to be freed.
  72  *
  73  * TOAST_HAS_NULLS indicates that nulls were found in the tuple being toasted.
  74  *
  75  * TOAST_NEEDS_CHANGE indicates that a new tuple needs to built; in other
  76  * words, the toaster did something.
  77  */
  78 #define TOAST_NEEDS_DELETE_OLD                          0x0001
  79 #define TOAST_NEEDS_FREE                                        0x0002
  80 #define TOAST_HAS_NULLS                                         0x0004
  81 #define TOAST_NEEDS_CHANGE                                      0x0008
  82
  83 /*
  84  * Flags indicating the status of a TOAST operation with respect to a
  85  * particular column.
  86  *
  87  * TOASTCOL_NEEDS_DELETE_OLD indicates that the old TOAST datums for this
  88  * column need to be deleted.
  89  *
  90  * TOASTCOL_NEEDS_FREE indicates that the value for this column needs to
  91  * be freed.
  92  *
  93  * TOASTCOL_IGNORE indicates that the toaster should not further process
  94  * this column.
  95  *
  96  * TOASTCOL_INCOMPRESSIBLE indicates that this column has been found to
  97  * be incompressible, but could be moved out-of-line.
  98  */
  99 #define TOASTCOL_NEEDS_DELETE_OLD                       TOAST_NEEDS_DELETE_OLD
 100 #define TOASTCOL_NEEDS_FREE                                     TOAST_NEEDS_FREE
 101 #define TOASTCOL_IGNORE                                         0x0010
 102 #define TOASTCOL_INCOMPRESSIBLE                         0x0020
 103
 104 extern void toast_tuple_init(ToastTupleContext *ttc);
 105 extern int      toast_tuple_find_biggest_attribute(ToastTupleContext *ttc,
 106                                                                                            bool for_compression,
 107                                                                                            bool check_main);
 108 extern void toast_tuple_try_compression(ToastTupleContext *ttc, int attribute);
 109 extern void toast_tuple_externalize(ToastTupleContext *ttc, int attribute,
 110                                                                         int options);
 111 extern void toast_tuple_cleanup(ToastTupleContext *ttc);
 112
 113 extern void toast_delete_external(Relation rel, Datum *values, bool *isnull,
 114                                                                   bool is_speculative);
 115
 116 #endif