src/include/access/heapam.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * heapam.h
   4  *        POSTGRES heap access method definitions.
   5  *
   6  *
   7  * Portions Copyright (c) 1996-2008, PostgreSQL Global Development Group
   8  * Portions Copyright (c) 1994, Regents of the University of California
   9  *
  10  * $PostgreSQL$
  11  *
  12  *-------------------------------------------------------------------------
  13  */
  14 #ifndef HEAPAM_H
  15 #define HEAPAM_H
  16
  17 #include "access/htup.h"
  18 #include "access/relscan.h"
  19 #include "access/sdir.h"
  20 #include "access/tupmacs.h"
  21 #include "access/xlogutils.h"
  22 #include "nodes/primnodes.h"
  23 #include "storage/block.h"
  24 #include "storage/lmgr.h"
  25 #include "utils/rel.h"
  26 #include "utils/snapshot.h"
  27
  28 /* ----------------
  29  *              fastgetattr
  30  *
  31  *              Fetch a user attribute's value as a Datum (might be either a
  32  *              value, or a pointer into the data area of the tuple).
  33  *
  34  *              This must not be used when a system attribute might be requested.
  35  *              Furthermore, the passed attnum MUST be valid.  Use heap_getattr()
  36  *              instead, if in doubt.
  37  *
  38  *              This gets called many times, so we macro the cacheable and NULL
  39  *              lookups, and call nocachegetattr() for the rest.
  40  * ----------------
  41  */
  42
  43 #if !defined(DISABLE_COMPLEX_MACRO)
  44
  45 #define fastgetattr(tup, attnum, tupleDesc, isnull)                                     \
  46 (                                                                                                                                       \
  47         AssertMacro((attnum) > 0),                                                                              \
  48         (((isnull) != NULL) ? (*(isnull) = false) : (dummyret)NULL),                            \
  49         HeapTupleNoNulls(tup) ?                                                                                 \
  50         (                                                                                                                               \
  51                 (tupleDesc)->attrs[(attnum)-1]->attcacheoff >= 0 ?                      \
  52                 (                                                                                                                       \
  53                         fetchatt((tupleDesc)->attrs[(attnum)-1],                                \
  54                                 (char *) (tup)->t_data + (tup)->t_data->t_hoff +        \
  55                                         (tupleDesc)->attrs[(attnum)-1]->attcacheoff)    \
  56                 )                                                                                                                       \
  57                 :                                                                                                                       \
  58                         nocachegetattr((tup), (attnum), (tupleDesc), (isnull))  \
  59         )                                                                                                                               \
  60         :                                                                                                                               \
  61         (                                                                                                                               \
  62                 att_isnull((attnum)-1, (tup)->t_data->t_bits) ?                         \
  63                 (                                                                                                                       \
  64                         (((isnull) != NULL) ? (*(isnull) = true) : (dummyret)NULL),             \
  65                         (Datum)NULL                                                                                             \
  66                 )                                                                                                                       \
  67                 :                                                                                                                       \
  68                 (                                                                                                                       \
  69                         nocachegetattr((tup), (attnum), (tupleDesc), (isnull))  \
  70                 )                                                                                                                       \
  71         )                                                                                                                               \
  72 )
  73 #else                                                   /* defined(DISABLE_COMPLEX_MACRO) */
  74
  75 extern Datum fastgetattr(HeapTuple tup, int attnum, TupleDesc tupleDesc,
  76                         bool *isnull);
  77 #endif   /* defined(DISABLE_COMPLEX_MACRO) */
  78
  79
  80 /* ----------------
  81  *              heap_getattr
  82  *
  83  *              Extract an attribute of a heap tuple and return it as a Datum.
  84  *              This works for either system or user attributes.  The given attnum
  85  *              is properly range-checked.
  86  *
  87  *              If the field in question has a NULL value, we return a zero Datum
  88  *              and set *isnull == true.  Otherwise, we set *isnull == false.
  89  *
  90  *              <tup> is the pointer to the heap tuple.  <attnum> is the attribute
  91  *              number of the column (field) caller wants.      <tupleDesc> is a
  92  *              pointer to the structure describing the row and all its fields.
  93  * ----------------
  94  */
  95 #define heap_getattr(tup, attnum, tupleDesc, isnull) \
  96 ( \
  97         AssertMacro((tup) != NULL), \
  98         ( \
  99                 ((attnum) > 0) ? \
 100                 ( \
 101                         ((attnum) > (int) HeapTupleHeaderGetNatts((tup)->t_data)) ? \
 102                         ( \
 103                                 (((isnull) != NULL) ? (*(isnull) = true) : (dummyret)NULL), \
 104                                 (Datum)NULL \
 105                         ) \
 106                         : \
 107                                 fastgetattr((tup), (attnum), (tupleDesc), (isnull)) \
 108                 ) \
 109                 : \
 110                         heap_getsysattr((tup), (attnum), (tupleDesc), (isnull)) \
 111         ) \
 112 )
 113
 114
 115 typedef enum
 116 {
 117         LockTupleShared,
 118         LockTupleExclusive
 119 } LockTupleMode;
 120
 121
 122 /* ----------------
 123  *              function prototypes for heap access method
 124  *
 125  * heap_create, heap_create_with_catalog, and heap_drop_with_catalog
 126  * are declared in catalog/heap.h
 127  * ----------------
 128  */
 129
 130 /* in heap/heapam.c */
 131 extern Relation relation_open(Oid relationId, LOCKMODE lockmode);
 132 extern Relation try_relation_open(Oid relationId, LOCKMODE lockmode);
 133 extern Relation relation_open_nowait(Oid relationId, LOCKMODE lockmode);
 134 extern Relation relation_openrv(const RangeVar *relation, LOCKMODE lockmode);
 135 extern void relation_close(Relation relation, LOCKMODE lockmode);
 136
 137 extern Relation heap_open(Oid relationId, LOCKMODE lockmode);
 138 extern Relation heap_openrv(const RangeVar *relation, LOCKMODE lockmode);
 139
 140 #define heap_close(r,l)  relation_close(r,l)
 141
 142 extern HeapScanDesc heap_beginscan(Relation relation, Snapshot snapshot,
 143                            int nkeys, ScanKey key);
 144 extern HeapScanDesc heap_beginscan_strat(Relation relation, Snapshot snapshot,
 145                                          int nkeys, ScanKey key,
 146                                          bool allow_strat, bool allow_sync);
 147 extern HeapScanDesc heap_beginscan_bm(Relation relation, Snapshot snapshot,
 148                                   int nkeys, ScanKey key);
 149 extern void heap_rescan(HeapScanDesc scan, ScanKey key);
 150 extern void heap_endscan(HeapScanDesc scan);
 151 extern HeapTuple heap_getnext(HeapScanDesc scan, ScanDirection direction);
 152
 153 extern bool heap_fetch(Relation relation, Snapshot snapshot,
 154                    HeapTuple tuple, Buffer *userbuf, bool keep_buf,
 155                    Relation stats_relation);
 156 extern bool heap_release_fetch(Relation relation, Snapshot snapshot,
 157                                    HeapTuple tuple, Buffer *userbuf, bool keep_buf,
 158                                    Relation stats_relation);
 159 extern bool heap_hot_search_buffer(ItemPointer tid, Buffer buffer,
 160                                            Snapshot snapshot, bool *all_dead);
 161 extern bool heap_hot_search(ItemPointer tid, Relation relation,
 162                                 Snapshot snapshot, bool *all_dead);
 163
 164 extern void heap_get_latest_tid(Relation relation, Snapshot snapshot,
 165                                         ItemPointer tid);
 166 extern void setLastTid(const ItemPointer tid);
 167
 168 extern Oid heap_insert(Relation relation, HeapTuple tup, CommandId cid,
 169                         bool use_wal, bool use_fsm);
 170 extern HTSU_Result heap_delete(Relation relation, ItemPointer tid,
 171                         ItemPointer ctid, TransactionId *update_xmax,
 172                         CommandId cid, Snapshot crosscheck, bool wait);
 173 extern HTSU_Result heap_update(Relation relation, ItemPointer otid,
 174                         HeapTuple newtup,
 175                         ItemPointer ctid, TransactionId *update_xmax,
 176                         CommandId cid, Snapshot crosscheck, bool wait);
 177 extern HTSU_Result heap_lock_tuple(Relation relation, HeapTuple tuple,
 178                                 Buffer *buffer, ItemPointer ctid,
 179                                 TransactionId *update_xmax, CommandId cid,
 180                                 LockTupleMode mode, bool nowait);
 181 extern void heap_inplace_update(Relation relation, HeapTuple tuple);
 182 extern bool heap_freeze_tuple(HeapTupleHeader tuple, TransactionId cutoff_xid,
 183                                   Buffer buf);
 184
 185 extern Oid      simple_heap_insert(Relation relation, HeapTuple tup);
 186 extern void simple_heap_delete(Relation relation, ItemPointer tid);
 187 extern void simple_heap_update(Relation relation, ItemPointer otid,
 188                                    HeapTuple tup);
 189
 190 extern void heap_markpos(HeapScanDesc scan);
 191 extern void heap_restrpos(HeapScanDesc scan);
 192
 193 extern void heap_sync(Relation relation);
 194
 195 extern void heap_redo(XLogRecPtr lsn, XLogRecord *rptr);
 196 extern void heap_desc(StringInfo buf, uint8 xl_info, char *rec);
 197 extern void heap2_redo(XLogRecPtr lsn, XLogRecord *rptr);
 198 extern void heap2_desc(StringInfo buf, uint8 xl_info, char *rec);
 199
 200 extern XLogRecPtr log_heap_move(Relation reln, Buffer oldbuf,
 201                           ItemPointerData from,
 202                           Buffer newbuf, HeapTuple newtup);
 203 extern XLogRecPtr log_heap_clean(Relation reln, Buffer buffer,
 204                            OffsetNumber *redirected, int nredirected,
 205                            OffsetNumber *nowdead, int ndead,
 206                            OffsetNumber *nowunused, int nunused,
 207                            bool redirect_move);
 208 extern XLogRecPtr log_heap_freeze(Relation reln, Buffer buffer,
 209                                 TransactionId cutoff_xid,
 210                                 OffsetNumber *offsets, int offcnt);
 211 extern XLogRecPtr log_newpage(RelFileNode *rnode, BlockNumber blk, Page page);
 212
 213 /* in common/heaptuple.c */
 214 extern Size heap_compute_data_size(TupleDesc tupleDesc,
 215                                            Datum *values, bool *isnull);
 216 extern void heap_fill_tuple(TupleDesc tupleDesc,
 217                                 Datum *values, bool *isnull,
 218                                 char *data, Size data_size,
 219                                 uint16 *infomask, bits8 *bit);
 220 extern bool heap_attisnull(HeapTuple tup, int attnum);
 221 extern Datum nocachegetattr(HeapTuple tup, int attnum,
 222                            TupleDesc att, bool *isnull);
 223 extern Datum heap_getsysattr(HeapTuple tup, int attnum, TupleDesc tupleDesc,
 224                                 bool *isnull);
 225 extern HeapTuple heap_copytuple(HeapTuple tuple);
 226 extern void heap_copytuple_with_tuple(HeapTuple src, HeapTuple dest);
 227 extern HeapTuple heap_form_tuple(TupleDesc tupleDescriptor,
 228                                 Datum *values, bool *isnull);
 229 extern HeapTuple heap_formtuple(TupleDesc tupleDescriptor,
 230                            Datum *values, char *nulls);
 231 extern HeapTuple heap_modify_tuple(HeapTuple tuple,
 232                                   TupleDesc tupleDesc,
 233                                   Datum *replValues,
 234                                   bool *replIsnull,
 235                                   bool *doReplace);
 236 extern HeapTuple heap_modifytuple(HeapTuple tuple,
 237                                  TupleDesc tupleDesc,
 238                                  Datum *replValues,
 239                                  char *replNulls,
 240                                  char *replActions);
 241 extern void heap_deform_tuple(HeapTuple tuple, TupleDesc tupleDesc,
 242                                   Datum *values, bool *isnull);
 243 extern void heap_deformtuple(HeapTuple tuple, TupleDesc tupleDesc,
 244                                  Datum *values, char *nulls);
 245 extern void heap_freetuple(HeapTuple htup);
 246 extern MinimalTuple heap_form_minimal_tuple(TupleDesc tupleDescriptor,
 247                                                 Datum *values, bool *isnull);
 248 extern void heap_free_minimal_tuple(MinimalTuple mtup);
 249 extern MinimalTuple heap_copy_minimal_tuple(MinimalTuple mtup);
 250 extern HeapTuple heap_tuple_from_minimal_tuple(MinimalTuple mtup);
 251 extern MinimalTuple minimal_tuple_from_heap_tuple(HeapTuple htup);
 252 extern HeapTuple heap_addheader(int natts, bool withoid,
 253                            Size structlen, void *structure);
 254
 255 /* in heap/pruneheap.c */
 256 extern void heap_page_prune_opt(Relation relation, Buffer buffer,
 257                                         TransactionId OldestXmin);
 258 extern int heap_page_prune(Relation relation, Buffer buffer,
 259                                 TransactionId OldestXmin,
 260                                 bool redirect_move, bool report_stats);
 261 extern void heap_page_prune_execute(Relation reln, Buffer buffer,
 262                                                 OffsetNumber *redirected, int nredirected,
 263                                                 OffsetNumber *nowdead, int ndead,
 264                                                 OffsetNumber *nowunused, int nunused,
 265                                                 bool redirect_move);
 266 extern void heap_get_root_tuples(Page page, OffsetNumber *root_offsets);
 267
 268 /* in heap/syncscan.c */
 269 extern void ss_report_location(Relation rel, BlockNumber location);
 270 extern BlockNumber ss_get_location(Relation rel, BlockNumber relnblocks);
 271 extern void SyncScanShmemInit(void);
 272 extern Size SyncScanShmemSize(void);
 273
 274 #endif   /* HEAPAM_H */