Line data    Source code

       1             : /*-------------------------------------------------------------------------
       2             :  *
       3             :  * tidbitmap.h
       4             :  *    PostgreSQL tuple-id (TID) bitmap package
       5             :  *
       6             :  * This module provides bitmap data structures that are spiritually
       7             :  * similar to Bitmapsets, but are specially adapted to store sets of
       8             :  * tuple identifiers (TIDs), or ItemPointers.  In particular, the division
       9             :  * of an ItemPointer into BlockNumber and OffsetNumber is catered for.
      10             :  * Also, since we wish to be able to store very large tuple sets in
      11             :  * memory with this data structure, we support "lossy" storage, in which
      12             :  * we no longer remember individual tuple offsets on a page but only the
      13             :  * fact that a particular page needs to be visited.
      14             :  *
      15             :  *
      16             :  * Copyright (c) 2003-2025, PostgreSQL Global Development Group
      17             :  *
      18             :  * src/include/nodes/tidbitmap.h
      19             :  *
      20             :  *-------------------------------------------------------------------------
      21             :  */
      22             : #ifndef TIDBITMAP_H
      23             : #define TIDBITMAP_H
      24             : 
      25             : #include "storage/itemptr.h"
      26             : #include "utils/dsa.h"
      27             : 
      28             : 
      29             : /*
      30             :  * Actual bitmap representation is private to tidbitmap.c.  Callers can
      31             :  * do IsA(x, TIDBitmap) on it, but nothing else.
      32             :  */
      33             : typedef struct TIDBitmap TIDBitmap;
      34             : 
      35             : /* Likewise, TBMPrivateIterator is private */
      36             : typedef struct TBMPrivateIterator TBMPrivateIterator;
      37             : typedef struct TBMSharedIterator TBMSharedIterator;
      38             : 
      39             : /*
      40             :  * Callers with both private and shared implementations can use this unified
      41             :  * API.
      42             :  */
      43             : typedef struct TBMIterator
      44             : {
      45             :     bool        shared;
      46             :     union
      47             :     {
      48             :         TBMPrivateIterator *private_iterator;
      49             :         TBMSharedIterator *shared_iterator;
      50             :     }           i;
      51             : } TBMIterator;
      52             : 
      53             : /* Result structure for tbm_iterate */
      54             : typedef struct TBMIterateResult
      55             : {
      56             :     BlockNumber blockno;        /* page number containing tuples */
      57             :     int         ntuples;        /* -1 indicates lossy result */
      58             :     bool        recheck;        /* should the tuples be rechecked? */
      59             :     /* Note: recheck is always true if ntuples < 0 */
      60             :     OffsetNumber offsets[FLEXIBLE_ARRAY_MEMBER];
      61             : } TBMIterateResult;
      62             : 
      63             : /* function prototypes in nodes/tidbitmap.c */
      64             : 
      65             : extern TIDBitmap *tbm_create(long maxbytes, dsa_area *dsa);
      66             : extern void tbm_free(TIDBitmap *tbm);
      67             : extern void tbm_free_shared_area(dsa_area *dsa, dsa_pointer dp);
      68             : 
      69             : extern void tbm_add_tuples(TIDBitmap *tbm,
      70             :                            const ItemPointer tids, int ntids,
      71             :                            bool recheck);
      72             : extern void tbm_add_page(TIDBitmap *tbm, BlockNumber pageno);
      73             : 
      74             : extern void tbm_union(TIDBitmap *a, const TIDBitmap *b);
      75             : extern void tbm_intersect(TIDBitmap *a, const TIDBitmap *b);
      76             : 
      77             : extern bool tbm_is_empty(const TIDBitmap *tbm);
      78             : 
      79             : extern TBMPrivateIterator *tbm_begin_private_iterate(TIDBitmap *tbm);
      80             : extern dsa_pointer tbm_prepare_shared_iterate(TIDBitmap *tbm);
      81             : extern TBMIterateResult *tbm_private_iterate(TBMPrivateIterator *iterator);
      82             : extern TBMIterateResult *tbm_shared_iterate(TBMSharedIterator *iterator);
      83             : extern void tbm_end_private_iterate(TBMPrivateIterator *iterator);
      84             : extern void tbm_end_shared_iterate(TBMSharedIterator *iterator);
      85             : extern TBMSharedIterator *tbm_attach_shared_iterate(dsa_area *dsa,
      86             :                                                     dsa_pointer dp);
      87             : extern long tbm_calculate_entries(double maxbytes);
      88             : 
      89             : extern TBMIterator tbm_begin_iterate(TIDBitmap *tbm,
      90             :                                      dsa_area *dsa, dsa_pointer dsp);
      91             : extern void tbm_end_iterate(TBMIterator *iterator);
      92             : 
      93             : extern TBMIterateResult *tbm_iterate(TBMIterator *iterator);
      94             : 
      95             : static inline bool
      96     5799492 : tbm_exhausted(TBMIterator *iterator)
      97             : {
      98             :     /*
      99             :      * It doesn't matter if we check the private or shared iterator here. If
     100             :      * tbm_end_iterate() was called, they will be NULL
     101             :      */
     102     5799492 :     return !iterator->i.private_iterator;
     103             : }
     104             : 
     105             : #endif                          /* TIDBITMAP_H */