postgresql/src/include/access/gist.h

/*-------------------------------------------------------------------------
 *
 * gist.h--
 *    common declarations for the GiST access method code.
 *
 *
 *
 * 
 *
 *-------------------------------------------------------------------------
 */
#ifndef GIST_H
#define GIST_H

#include <access/funcindex.h>
#include <access/itup.h>
#include <access/relscan.h>
#include <access/sdir.h>
#include <storage/page.h>
#include <storage/block.h>
#include <utils/rel.h>
#include <storage/off.h>

/* 
** You can have as many strategies as you please in GiSTs, as
** long as your consistent method can handle them
**
** But strat.h->StrategyEvaluationData->StrategyExpression  expression[12]
** - so 12 is real max # of strategies, or StrategyEvaluationIsValid
** crashes backend...		- vadim 05/21/97

#define GISTNStrategies			100

*/
#define GISTNStrategies			12

/*
** Helper routines
*/
#define GISTNProcs			8
#define GIST_CONSISTENT_PROC		1
#define GIST_UNION_PROC			2
#define GIST_COMPRESS_PROC		3
#define GIST_DECOMPRESS_PROC		4
#define GIST_PENALTY_PROC		5
#define GIST_PICKSPLIT_PROC		6
#define GIST_EQUAL_PROC 		7
#define GIST_INFO_PROC			8

#define F_LEAF		(1 << 0)

typedef struct GISTPageOpaqueData {
	uint32		flags;
} GISTPageOpaqueData;

typedef GISTPageOpaqueData	*GISTPageOpaque;

#define GIST_LEAF(entry) (((GISTPageOpaque) PageGetSpecialPointer((entry)->page))->flags & F_LEAF)

/*
 *  When we descend a tree, we keep a stack of parent pointers.
 */

typedef struct GISTSTACK {
	struct GISTSTACK *gs_parent;
	OffsetNumber	gs_child;
	BlockNumber	gs_blk;
} GISTSTACK;

typedef struct GISTSTATE {
    func_ptr consistentFn;
    func_ptr unionFn;
    func_ptr compressFn;
    func_ptr decompressFn;
    func_ptr penaltyFn;
    func_ptr picksplitFn;
    func_ptr equalFn;
    bool     haskeytype;
    bool     keytypbyval;
} GISTSTATE;


/*
**  When we're doing a scan, we need to keep track of the parent stack
**  for the marked and current items.  
*/

typedef struct GISTScanOpaqueData {
	struct GISTSTACK	*s_stack;
	struct GISTSTACK	*s_markstk;
	uint16		s_flags;
	struct GISTSTATE        *giststate;
} GISTScanOpaqueData;

typedef GISTScanOpaqueData	*GISTScanOpaque;

/*
**  When we're doing a scan and updating a tree at the same time, the
**  updates may affect the scan.  We use the flags entry of the scan's
**  opaque space to record our actual position in response to updates
**  that we can't handle simply by adjusting pointers.
*/

#define GS_CURBEFORE	((uint16) (1 << 0))
#define GS_MRKBEFORE	((uint16) (1 << 1))

/* root page of a gist */
#define GISTP_ROOT		0

/*
**  When we update a relation on which we're doing a scan, we need to
**  check the scan and fix it if the update affected any of the pages it
**  touches.  Otherwise, we can miss records that we should see.  The only
**  times we need to do this are for deletions and splits.  See the code in
**  gistscan.c for how the scan is fixed. These two constants tell us what sort
**  of operation changed the index.
*/

#define	GISTOP_DEL	0
#define	GISTOP_SPLIT	1

/*
** This is the Split Vector to be returned by the PickSplit method.
*/
typedef struct GIST_SPLITVEC {
    OffsetNumber	*spl_left;    /* array of entries that go left */
    int			spl_nleft;    /* size of this array */
    char		*spl_ldatum;  /* Union of keys in spl_left */
    OffsetNumber	*spl_right;   /* array of entries that go right */
    int			spl_nright;   /* size of the array */
    char		*spl_rdatum;  /* Union of keys in spl_right */
} GIST_SPLITVEC;

/*
** An entry on a GiST node.  Contains the key (pred), as well as 
** its own location (rel,page,offset) which can supply the matching
** pointer.  The size of the pred is in bytes, and leafkey is a flag to
** tell us if the entry is in a leaf node.
*/
typedef struct GISTENTRY {
    char *pred;
    Relation rel;
    Page page;
    OffsetNumber offset;
    int bytes;
    bool leafkey;
} GISTENTRY;

/*
** macro to initialize a GISTENTRY
*/
#define gistentryinit(e, pr, r, pg, o, b, l)\
   {(e).pred = pr; (e).rel = r; (e).page = pg; (e).offset = o; (e).bytes = b; (e).leafkey = l;}

/* defined in gist.c */
#define TRLOWER(tr) (((tr)->bytes))
#define TRUPPER(tr) (&((tr)->bytes[MAXALIGN(VARSIZE(TRLOWER(tr)))]))

typedef struct txtrange {
    /* flag: NINF means that lower is negative infinity; PINF means that
    ** upper is positive infinity.  0 means that both are numbers.
    */
    int32 vl_len;
    int32 flag;  
    char bytes[2];
} TXTRANGE;

typedef struct intrange {
    int lower;
    int upper;
    /* flag: NINF means that lower is negative infinity; PINF means that
    ** upper is positive infinity.  0 means that both are numbers.
    */
    int flag;  
} INTRANGE;

extern void gistbuild(Relation heap,
	  Relation index, int natts,
	  AttrNumber *attnum, IndexStrategy istrat,
	  uint16 pint, Datum *params,
	  FuncIndexInfo *finfo,
	  PredInfo *predInfo);
extern InsertIndexResult gistinsert(Relation r, Datum *datum,
			char *nulls,ItemPointer ht_ctid, Relation heapRel);
extern void _gistdump(Relation r);
extern void gistfreestack(GISTSTACK *s);
extern void initGISTstate(GISTSTATE *giststate, Relation index);
extern void gistdentryinit(GISTSTATE *giststate, GISTENTRY *e, char *pr, 
			   Relation r, Page pg, OffsetNumber o, int b, bool l) ;
extern StrategyNumber RelationGetGISTStrategy(Relation, AttrNumber, RegProcedure);

/* gistget.c */
extern RetrieveIndexResult gistgettuple(IndexScanDesc s, ScanDirection dir);

#endif /* GIST_H */