gdk.mx

来自「这个是内存数据库中的一个管理工具」· MX 代码 · 共 1,875 行 · 第 1/5 页

@item @code{BAT* }
@tab BATextend (BAT *b, size_t newcap)
@end multitable
@
A temporary BAT is instantiated using @%BATnew@ with the type aliases of
the required binary association. The aliases include the built-in
types, such as @%TYPE_int@....@%TYPE_ptr@, and the atomic types introduced
by the user. The initial capacity to be accommodated within a BAT is
indicated by @%cap@.
Their extend is automatically incremented upon storage overflow.
Failure to create the BAT results in a NULL pointer.
@
The routine @%BATclone@ creates an empty BAT storage area with the properties
inherited from its argument. 
@{
@h
#define BATDELETE	-9999

gdk_export BAT *BATnew(int hdtype, int tltype, size_t capacity);
gdk_export BAT *BATclone(BAT *b, size_t capacity);
gdk_export BAT *BATextend(BAT *b, size_t newcap);

/* internal */
gdk_export BAT *BATnewstorage(int ht, int tt, size_t cap);
gdk_export BAT *BATcreatedesc(int ht, int tt, int heapnames);
gdk_export int BATfree(BAT *b);
gdk_export void BATdestroy(BAT *b);
gdk_export int BATelmshift(BAT *b);
gdk_export void BATsetdims(BAT *b);
@
@}



@- BUN manipulation
@multitable @columnfractions 0.08 0.7
@item BAT*
@tab BATins (BAT *b, BAT *c, bit force)
@item BAT*
@tab BATappend (BAT *b, BAT *c, bit force)
@item BAT*
@tab BATdel (BAT *b, BAT *c, bit force)
@item BAT*
@tab BUNins (BAT *b, ptr left, ptr right, bit force)
@item BAT*
@tab BUNappend (BAT *b, ptr right, bit force)
@item BAT*
@tab BUNreplace (BAT *b, ptr left, ptr right, bit force)
@item int
@tab BUNdel (BAT *b, ptr left, ptr right, bit force)
@item int
@tab BUNdelHead (BAT *b, ptr left, bit force)
@item BUN
@tab BUNfnd (BAT *b, ptr head)
@item void
@tab BUNfndOID (BUN result, BAT *b, oid *head)
@item void
@tab BUNfndSTD (BUN result, BAT *b, ptr head)
@item BUN
@tab BUNlocate (BAT *b, ptr head, ptr tail)
@item ptr
@tab BUNhead (BAT *b, BUN p)
@item ptr
@tab BUNtail (BAT *b, BUN p)
@end multitable
@
The BATs contain a number of fixed-sized slots to store the binary
associations.  These slots are called BUNs or BAT units. A BUN
variable is a pointer into the storage area of the BAT, but it has
limited validity. After a BAT modification, previously obtained BUNs
may no longer reside at the same location.
@
The association list does not contain holes.  This density permits
users to quickly access successive elements without the need to test
the items for validity. Moreover, it simplifies transport to disk and
other systems. The negative effect is that the user should be aware of
the evolving nature of the sequence, which may require copying the BAT
first.
@
The update operations come in three flavors. Element-wise updates
can use @%BUNins@, @%BUNappend@, @%BUNreplace@, @%BUNdel@, and @%BUNdelHead@.
The batch update operations are @%BATins@, @%BATappend@ and @%BATdel@.
@
Only experts interested in speed may use @%BUNfastins@, since it skips most
consistency checks, does not update search accelerators, and does
not maintain properties such as the @%hsorted@ and @%tsorted@ flags. Beware!
@
The routine @%BUNfnd@ provides fast access to a single BUN providing
a value for the head of the binary association.
A very fast shortcut for @%BUNfnd@ if the selection type is known to be
integer or OID, is provided in the form of the macro @%BUNfndOID@.
@
To select on a tail, one should use the reverse view obtained by
@%BATmirror@.
@
The routines @%BUNhead@ and @%BUNtail@ return a pointer to the first
and second value in an association, respectively.  To guard against
side effects on the BAT, one should normally copy this value into a
scratch variable for further processing.

Behind the interface we use several macros to access the BUN fixed
part and the variable part. The BUN operators always require a BAT pointer
and BUN identifier.
@itemize
@item
BAThtype(b) and  BATttype(b) find out the head and tail type of a BAT.
@item
BUNfirst(b) returns a BUN pointer to the first BUN as a BAT.
@item
BUNlast(b) returns the BUN pointer directly after the last BUN
in the BAT.
@item
BUNsize(b) gives the size in bytes of each BUN.
@item
BUNindex(b, p) computes the index number of a given BUN.
@item
BUNptr(b, i) computes the address of the i-th BUN in the BAT.
@item
BUNhead(b, p) and BUNtail(b, p) return pointers to the
head-value and tail-value in a given BUN.
@item
BUNhloc(b, p) and BUNtloc(b, p) do the same thing, but knowing
in advance that the head-atom resp. tail-atom of a BAT is fixed size.
@item
BUNhvar(b, p) and BUNtvar(b, p) do the same thing, but knowing
in advance that the head-atom resp. tail-atom of a BAT is variable sized.
@end itemize
@{
@h
#define bunfastins_nocheck(b, p, h, t, s) {				\
		(b)->batBuns->free += s;				\
		(b)->batCount ++;				        \
		ATOMput((b)->htype, (b)->hheap, BUNhloc(b, p), h);	\
		ATOMput((b)->ttype, (b)->theap, BUNtloc(b, p), t);	\
	}

#define bunfastins(b, h, t) {						\
		REGISTER BUN _p = BUNlast(b);				\
		REGISTER size_t _bunsize = BUNsize(b);			\
		if ((b)->batBuns->free + _bunsize > (b)->batBuns->size) { \
			if (BATextend((b), BATgrows(b)) == NULL) goto bunins_failed; \
			_p = BUNlast(b);				\
		}							\
		bunfastins_nocheck(b, _p, h, t, _bunsize);		\
	}

gdk_export BAT *BUNfastins(BAT *b, ptr left, ptr right);
gdk_export BAT *BUNins(BAT *b, ptr left, ptr right, bit force);
gdk_export BAT *BUNappend(BAT *b, ptr right, bit force);
gdk_export BAT *BATins(BAT *b, BAT *c, bit force);
gdk_export BAT *BATappend(BAT *b, BAT *c, bit force);
gdk_export BAT *BUNdel(BAT *b, ptr left, ptr right, bit force);
gdk_export BAT *BUNdelHead(BAT *b, ptr left, bit force);
gdk_export BUN BUNdelete(BAT *b, BUN p, bit force);
gdk_export BAT *BATdel(BAT *b, BAT *c, bit force);
gdk_export BAT *BATdelHead(BAT *b, BAT *c, bit force);

gdk_export BAT *BUNreplace(BAT *b, ptr left, ptr right, bit force);
gdk_export BAT *BUNinplace(BAT *b, BUN p, ptr left, ptr right, bit force);
gdk_export BAT *BATreplace(BAT *b, BAT *n, bit force);

gdk_export BUN BUNlocate(BAT *b, ptr left, ptr right);
gdk_export BUN BUNfnd(BAT *b, ptr left);

#define BUNfndVOID(p,b,v) {                                                             \
    ssize_t result = ((ssize_t) BUNfirst(b)) + BUNsize(b)*(*(oid*)(v) - (b)->hseqbase); \
    ssize_t check = (((*(oid*) (v) == oid_nil) ^ ((b)->hseqbase == oid_nil)) |          \
                    (*(oid*) v < (b)->hseqbase) |                                       \
                    (*(oid*) v >= (b)->hseqbase + (b)->batCount));                      \
    p = (BUN) (result&(check-1)); /* and with 0xFF...FF or 0x00..00 */                  \
}
#if SIZEOF_OID == SIZEOF_INT
#define BUNfndOID(p,b,v)			\
	if (BAThdense(b)) {			\
		BUNfndVOID(p,b,v);		\
	} else {				\
		HASHfnd_int(p,b,(int*)v);	\
	}
#else
#define BUNfndOID(p,b,v)			\
	if (BAThdense(b)) {			\
		BUNfndVOID(p,b,v);		\
	} else {				\
		HASHfnd_lng(p,b,(lng*)v);	\
	}
#endif
#define BUNfndSTD(p,b,v) ((p) = BUNfnd(b,v))

#define BAThtype(b)	((b)->htype == TYPE_void && (b)->hseqbase == oid_nil ?\
				TYPE_void : ATOMtype((b)->htype))
#define BATttype(b)	((b)->ttype == TYPE_void && (b)->tseqbase == oid_nil ?\
				TYPE_void : ATOMtype((b)->ttype))
#define BAThstore(b)	(BAThdense(b) ? TYPE_void : (b)->htype)
#define BATtstore(b)	(BATtdense(b) ? TYPE_void : (b)->ttype)
#define Bunbase(b)	((b)->batBuns->base)
#define Hbase(b)	((b)->hheap->base)
#define Tbase(b)	((b)->theap->base)

#define BUNhead(b,p)	((b)->hvarsized ? BUNhvar(b,p) : BUNhloc(b,p))
#define BUNtail(b,p)	((b)->tvarsized ? BUNtvar(b,p) : BUNtloc(b,p))

#define BUNsize(b)	((b)->dims.bunwidth)
#define BUNptr(b,i)	((BUN) ((char *) Bunbase(b) + (i) * BUNsize(b)))
#define BUNindex(b,p)	((size_t) ((b)->batElmshift < 0 ? \
				   (((char*)(p)-(char*)Bunbase(b))/BUNsize(b)) : \
				   (((char*)(p)-(char*)Bunbase(b)) >> (b)->batElmshift)))

#define BUNhloc(b,p)	((BUN) (((char *) (p)) + (b)->hloc))
#define BUNtloc(b,p)	((BUN) (((char *) (p)) + (b)->tloc))
#define BUNhvar(b,p)	((b)->htype?(BUN)((char *) Hbase(b)+*(var_t*)BUNhloc(b,p)):(BUN)BUNhpos(b,p))
#define BUNtvar(b,p)	((b)->ttype?(BUN)((char *) Tbase(b)+*(var_t*)BUNtloc(b,p)):(BUN)BUNtpos(b,p))

#define BUNfirst(b)	((BUN) (b)->batFirst)
#define BUNlast(b)	((BUN) ((char *) Bunbase(b) + (b)->batBuns->free))
#define BUNnext(b,p)	((BUN) ((char *) (p) + BUNsize(b)))
#define BUNprev(b,p)	((BUN) ((char *) (p) - BUNsize(b)))

#define BUNgetpos(b,p)	(((b)->batElmshift < 0)?\
				((p-BUNfirst(b)) / BUNsize(b)):\
				((p-BUNfirst(b)) >> (b)->batElmshift))
@
@}

@- BAT properties
@multitable @columnfractions 0.08 0.7
@item size_t
@tab BATcount (BAT *b)
@item size_t
@tab BATbuncount (BAT *b)
@item str
@tab BATrename (BAT *b, str nme)
@item BAT *
@tab BATkey (BAT *b, int onoff)
@item BAT *
@tab BATset (BAT *b, int onoff)
@item BAT *
@tab BATmode (BAT *b, int mode)
@item BAT *
@tab BATsetaccess (BAT *b, int mode)
@item int
@tab BATdirty (BAT *b)
@item int
@tab BATgetaccess (BAT *b)
@item int
@tab BATversion (BAT *b)
@end multitable
@
The function @%BATcount@ returns the number of associations
stored in the BAT.
@
The function @%BATbuncount@ returns the space that is occupied in
associations in the BAT. This is not the same as @%BATcount@,
since the first N associations may be unused or delta data.
@
The BAT is given a new logical name using @%BATrename@.
@
The integrity properties to be maintained for the BAT are controlled separately.
A key property indicates that duplicates
in the association dimension are not permitted. The BAT is turned into
a set of associations using @%BATset@. Key and set properties
are orthogonal integrity constraints.
The strongest reduction is obtained by making the BAT a set with key
restrictions on both dimensions.
@
The persistency indicator tells the retention period of BATs.
The system support three modes:
PERSISTENT, TRANSIENT, and SESSION.
The PERSISTENT BATs are automatically saved upon session boundary or
transaction commit.
TRANSIENT BATs are removed upon transaction boundary.
SESSION BATs are removed at the end of a session.
They are normally used to maintain temporary results.
All BATs are initially TRANSIENT unless their mode is changed
using the routine @%BATmode@.
@
The BAT properties may be changed at any time using @%BATkey@, @%BATset@,
and @%BATmode@.

Valid BAT access properties can be set with @%BATsetaccess@ and @%BATgetaccess@:
BAT_READ, BAT_APPEND, and BAT_WRITE.
BATs can be designated to be read-only. In this case some
memory optimizations may be made (slice and fragment bats can point
to stable subsets of a parent bat).
A special mode is append-only. It is then allowed to insert BUNs
at the end of the BAT, but not to modify anything that already
was in there.
@{
@h
gdk_export str BATrename(BAT *b, str nme);
gdk_export size_t BATcount(BAT *b);
gdk_export size_t BATcount_no_nil(BAT *b);
gdk_export size_t BATbuncount(BAT *b);
gdk_export size_t BATguess(BAT *b);
gdk_export size_t BATgrows(BAT *b);
gdk_export BAT *BATkey(BAT *b, int onoff);
gdk_export BAT *BATset(BAT *b, int onoff);
gdk_export BAT *BATmode(BAT *b, int onoff);
gdk_export BAT *BATroles(BAT *b, str hnme, str tnme);
gdk_export BAT *BATcol_name(BAT *b, str tnme);
gdk_export int BATname(BAT *b, str nme);
gdk_export BAT *BATseqbase(BAT *b, oid o);
gdk_export BAT *BATsetaccess(BAT *b, int mode);
gdk_export int BATgetaccess(BAT *b);
gdk_export int BATcheckmodes(BAT *b, int persistent, int unloadable);


#define BATdirty(b)	((b)->batCopiedtodisk == 0 || (b)->batDirty ||	\
			(b)->batDirtydesc || (b)->batDirtybuns ||	\
			(b)->hheapdirty || (b)->theapdirty)

#define PERSISTENT	4096
#define SESSION		2048
#define TRANSIENT	1024

#define BAT_WRITE		0	/* all kinds of access allowed */
#define BAT_READ		1	/* only read-access allowed */
#define BAT_APPEND		2	/* only reads and appends allowed */

#define BATversion(b)	(b)->GDKversion
#define BATcapacity(b)	((size_t) (((b)->batElmshift<0)?		\
				   (((b)->batBuns->size)/BUNsize(b)):	\
				   (((b)->batBuns->size) >> (b)->batElmshift)))
@
@}

@- BAT manipulation
@multitable @columnfractions 0.08 0.7
@item BAT *
@tab BATclear (BAT *b)
@item BAT *
@tab BATcopy (BAT *b, int ht, int tt, int writeable)
@item BAT *
@tab BATmark (BAT *b, oid base)
@item BAT *
@tab BATmark_grp (BAT *b, BAT *g)
@item BAT *
@tab BATnumber (BAT *b)
@item BAT *
@tab BATmirror (BAT *b)
@item BAT *
@tab BATreverse (BAT *b)
@item BAT *
@tab BATreset (BAT *b)
@end multitable
@
The routine @%BATclear@ removes the binary associations, leading
to an empty, but (re-)initialized BAT. Its properties are retained.
A temporary copy is obtained with @%BATcopy@. The new BAT has an unique name.
The routine @%BATmark@ creates a binary association that
introduces a new tail column of fresh densely ascending OIDs.
The base OID can be given explicitly, or if oid_nil is passed,
is chosen as a new unique range by the system.
A similar routine is @%BATnumber@, which copies the heads and
assigns an integer index to the tail.
It plays a crucial role in administration of query results.
@
The routine @%BATmirror@ returns the mirror image BAT (where tail is head
and head is tail) of that same BAT. This does not involve
a state change in the BAT (as previously): both views on the BAT
exist at the same time. 
@{
@h
gdk_export BAT *BATclear(BAT *b);
gdk_export BAT *BATcopy(BAT *b, int ht, int tt, int writeable);
gdk_export BAT *BATmark(BAT *b, oid base);
gdk_export BAT *BATnumber(BAT *b);
gdk_export BAT *BATgroup(BAT *b, int start, int incr, int grpsize);
@
@}


@- BAT Input/Output
@multitable @columnfractions 0.08 0.7
@item BAT *
@tab BATload (str name)