Changeset: 9be8bb5ebff5 for MonetDB
URL: http://dev.monetdb.org/hg/MonetDB?cmd=changeset;node=9be8bb5ebff5
Modified Files:
gdk/gdk_bbp.mx
Branch: Aug2011
Log Message:
Reformatted comments.
diffs (truncated from 1219 to 300 lines):
diff --git a/gdk/gdk_bbp.mx b/gdk/gdk_bbp.mx
--- a/gdk/gdk_bbp.mx
+++ b/gdk/gdk_bbp.mx
@@ -28,55 +28,60 @@ All Rights Reserved.
* @table @code
*
* @item administration and lookup
- * The BBP is a directory which contains status information about all known
BATs.
- * This interface may be used very heavily, by data-intensive applications.
- * To eliminate all overhead, read-only access to the BBP may be done by
- * table-lookups. The integer index type for these lookups is @emph{bat}, as
- * retrieved by @emph{BBPcacheid(b)}. The @emph{bat} zero is reserved for the
nil bat.
+ * The BBP is a directory which contains status information about all
+ * known BATs. This interface may be used very heavily, by
+ * data-intensive applications. To eliminate all overhead, read-only
+ * access to the BBP may be done by table-lookups. The integer index
+ * type for these lookups is @emph{bat}, as retrieved by
+ * @emph{BBPcacheid(b)}. The @emph{bat} zero is reserved for the nil
+ * bat.
*
* @item persistence
* The BBP is made persistent by saving it to the dictionary file
* called @emph{BBP.dir} in the database.
*
* When the number of BATs rises, having all files in one directory
- * becomes a bottleneck. The BBP therefore implements a scheme that
distributes
- * all BATs in a growing directory tree with at most 64 BATs stored in one
node.
+ * becomes a bottleneck. The BBP therefore implements a scheme that
+ * distributes all BATs in a growing directory tree with at most 64
+ * BATs stored in one node.
*
* @item buffer management
- * The BBP is responsible for loading and saving of BATs to disk. It also
- * contains routines to unload BATs from memory when memory resources
- * get scarce. For this purpose, it administers BAT memory reference
- * counts (to know which BATs can be unloaded) and BAT usage statistics
- * (it unloads the least recently used BATs).
+ * The BBP is responsible for loading and saving of BATs to disk. It
+ * also contains routines to unload BATs from memory when memory
+ * resources get scarce. For this purpose, it administers BAT memory
+ * reference counts (to know which BATs can be unloaded) and BAT usage
+ * statistics (it unloads the least recently used BATs).
*
* @item recovery
- * When the database is closed or during a run-time syncpoint, the system
- * tables must be written to disk in a safe way, that is immune for system
- * failures (like disk full). To do so, the BBP implements an atomic commit and
- * recovery protocol: first all files to be overwritten are moved to a BACKUP/
- * dir. If that succeeds, the writes are done. If that also fully succeeds
- * the BACKUP/ dir is renamed to DELETE_ME/ and subsequently deleted.
- * If not, all files in BACKUP/ are moved back to their original location.
+ * When the database is closed or during a run-time syncpoint, the
+ * system tables must be written to disk in a safe way, that is immune
+ * for system failures (like disk full). To do so, the BBP implements
+ * an atomic commit and recovery protocol: first all files to be
+ * overwritten are moved to a BACKUP/ dir. If that succeeds, the
+ * writes are done. If that also fully succeeds the BACKUP/ dir is
+ * renamed to DELETE_ME/ and subsequently deleted. If not, all files
+ * in BACKUP/ are moved back to their original location.
*
* @item unloading
* Bats which have a logical reference (ie. a lrefs > 0) but no memory
- * reference (refcnt == 0) can be unloaded. Unloading dirty bats means,
- * moving the original (committed version) to the BACKUP/ dir and saving
- * the bat. This complicates the commit and recovery/abort issues.
- * The commit has to check if the bat is already moved. And The recovery
- * has to always move back the files from the BACKUP/ dir.
+ * reference (refcnt == 0) can be unloaded. Unloading dirty bats
+ * means, moving the original (committed version) to the BACKUP/ dir
+ * and saving the bat. This complicates the commit and recovery/abort
+ * issues. The commit has to check if the bat is already moved. And
+ * The recovery has to always move back the files from the BACKUP/
+ * dir.
*
* @item reference counting
- * Bats use have two kinds of references: logical and physical (pointer) ones.
- * Both are administered with the BBPincref/BBPdecref routines. For
- * backward compatibility, we maintain BBPfix/BBPunfix as shorthands
- * for the adjusting the pointer references.
+ * Bats use have two kinds of references: logical and physical
+ * (pointer) ones. Both are administered with the BBPincref/BBPdecref
+ * routines. For backward compatibility, we maintain BBPfix/BBPunfix
+ * as shorthands for the adjusting the pointer references.
*
* @item share counting
* Views use the heaps of there parent bats. To save guard this, the
* parent has a shared counter, which is incremented and decremented
- * using BBPshare and BBPunshare. These functions make sure the
- * parent is memory resident as required because of the 'pointer' sharing.
+ * using BBPshare and BBPunshare. These functions make sure the parent
+ * is memory resident as required because of the 'pointer' sharing.
* @end table
*/
@h
@@ -147,13 +152,13 @@ gdk_export void BBPshare(bat b);
#include "gdk_storage.h"
#include "mutils.h"
/*
- * @-
* The BBP has a fixed address, so re-allocation due to a growing BBP
- * caused by one thread does not disturb reads to the old entries by another.
- * This is implemented using anonymous virtual memory; extensions on the same
- * address are guaranteed because a large non-committed VM area is requested
- * initially. New slots in the BBP are found in O(1) by keeping a freelist
- * that uses the 'next' field in the BBPrec records.
+ * caused by one thread does not disturb reads to the old entries by
+ * another. This is implemented using anonymous virtual memory;
+ * extensions on the same address are guaranteed because a large
+ * non-committed VM area is requested initially. New slots in the BBP
+ * are found in O(1) by keeping a freelist that uses the 'next' field
+ * in the BBPrec records.
*/
BBPrec *BBP = NULL; /* fixed base VM address of BBP array */
bat BBPmaxsize = BBPMAXSIZE; /* size of non-committed VM BBP array */
@@ -162,10 +167,9 @@ bat BBPsize = 0; /* current used size o
#define BBPNONAME "." /* filler for no name in BBP.dir */
/*
- * @-
* The hash index uses a bucket index (int array) of size mask that is
- * tuned for perfect hashing (1 lookup). The bucket chain uses the 'next'
- * field in the BBPrec records.
+ * tuned for perfect hashing (1 lookup). The bucket chain uses the
+ * 'next' field in the BBPrec records.
*/
@h
#define BBPtmpcheck(s) ((s)[0] == 't' && (s)[1] == 'm' && (s)[2] == 'p' &&
((s)[3] == '_' || ((s)[3] == 'r' && (s)[4] == '_'))) /* (strncmp((s),
"tmp_", 4) == 0) */
@@ -236,52 +240,61 @@ int BBPout = 0; /* bats saved statisti
* @+ BBP Consistency and Concurrency
* While GDK provides the basic building blocks for an ACID system, in
- * itself it is not such a system, as we this would entail too much overhead
- * that is often not needed. Hence, some consistency control is left to the
- * user. The first important user constraint is that if a user updates a
- * BAT, (s)he himself must assure that no-one else accesses this BAT.
+ * itself it is not such a system, as we this would entail too much
+ * overhead that is often not needed. Hence, some consistency control
+ * is left to the user. The first important user constraint is that if
+ * a user updates a BAT, (s)he himself must assure that no-one else
+ * accesses this BAT.
*
- * Concerning buffer management, the BBP carries out a swapping policy.
- * BATs are kept in memory till the memory is full. If the memory is full,
- * the malloc functions initiate BBP trim actions, that unload the coldest BATs
- * that have a zero reference count. The second important user constraint
- * is therefore that a user may only manipulate live BAT data in memory if it
- * is sure that there is at least one reference count to that BAT.
+ * Concerning buffer management, the BBP carries out a swapping
+ * policy. BATs are kept in memory till the memory is full. If the
+ * memory is full, the malloc functions initiate BBP trim actions,
+ * that unload the coldest BATs that have a zero reference count. The
+ * second important user constraint is therefore that a user may only
+ * manipulate live BAT data in memory if it is sure that there is at
+ * least one reference count to that BAT.
*
* The main BBP array is protected by two locks:
* @table @code
* @item GDKcacheLock]
- * this lock guards the free slot management in the BBP array. The BBP
- * operations that allocate a new slot for a new BAT
(@emph{BBPinit},@emph{BBPcacheit}),
- * delete the slot of a destroyed BAT (@emph{BBPreclaim}), or rename a BAT
- * (@emph{BBPrename}), hold this lock. It also protects all BAT (re)naming
actions
- * include (read and write) in the hash table with BAT names.
+ * this lock guards the free slot management in the BBP array. The
+ * BBP operations that allocate a new slot for a new BAT
+ * (@emph{BBPinit},@emph{BBPcacheit}), delete the slot of a destroyed
+ * BAT (@emph{BBPreclaim}), or rename a BAT (@emph{BBPrename}), hold
+ * this lock. It also protects all BAT (re)naming actions include
+ * (read and write) in the hash table with BAT names.
* @item GDKswapLock
- * this lock guards the swap (loaded/unloaded) status of the BATs. Hence, all
- * BBP routines that influence the swapping policy, or actually carry out the
- * swapping policy itself, acquire this lock (e.g.
@emph{BBPfix},@emph{BBPunfix}).
- * Note that this also means that updates to the BBP_status indicator array
- * must be protected by GDKswapLock.
+ * this lock guards the swap (loaded/unloaded) status of the
+ * BATs. Hence, all BBP routines that influence the swapping policy,
+ * or actually carry out the swapping policy itself, acquire this lock
+ * (e.g. @emph{BBPfix},@emph{BBPunfix}). Note that this also means
+ * that updates to the BBP_status indicator array must be protected by
+ * GDKswapLock.
*
- * To reduce contention GDKswapLock was split into multiple locks; it is now
- * an array of lock pointers which is accessed by GDKswapLock(ABS(bat))
+ * To reduce contention GDKswapLock was split into multiple locks; it
+ * is now an array of lock pointers which is accessed by
+ * GDKswapLock(ABS(bat))
* @end table
*
- * Routines that need both locks should first acquire the locks in the
GDKswapLock
- * array (in ascending order) and then GDKcacheLock (and release them in
reverse order).
+ * Routines that need both locks should first acquire the locks in the
+ * GDKswapLock array (in ascending order) and then GDKcacheLock (and
+ * release them in reverse order).
*
- * To obtain maximum speed, read operations to existing elements in the BBP are
- * unguarded. As said, it is the users responsibility that the BAT that is
being
- * read is not being modified. BBP update actions that modify the BBP data
structure
- * itself are locked by the BBP functions themselves. Hence, multiple
concurrent BBP read
- * operations may be ongoing while at the same time at most one BBP write
- * operation @strong{on a different BAT} is executing.
- * This holds for accesses to the public (quasi-)
- * arrays @emph{BBPcache}, @emph{BBPstatus}, @emph{BBPrefs}, @emph{BBPlogical}
and @emph{BBPphysical}. These
- * arrays are called quasi as now they are actually stored together in one big
BBPrec
- * array called BBP, that is allocated in anonymous VM space, so we can
reallocate
- * this structure without changing the base address (a crucial feature if read
- * actions are to go on unlocked while other entries in the BBP may be
modified).
+ * To obtain maximum speed, read operations to existing elements in
+ * the BBP are unguarded. As said, it is the users responsibility that
+ * the BAT that is being read is not being modified. BBP update
+ * actions that modify the BBP data structure itself are locked by the
+ * BBP functions themselves. Hence, multiple concurrent BBP read
+ * operations may be ongoing while at the same time at most one BBP
+ * write operation @strong{on a different BAT} is executing. This
+ * holds for accesses to the public (quasi-) arrays @emph{BBPcache},
+ * @emph{BBPstatus}, @emph{BBPrefs}, @emph{BBPlogical} and
+ * @emph{BBPphysical}. These arrays are called quasi as now they are
+ * actually stored together in one big BBPrec array called BBP, that
+ * is allocated in anonymous VM space, so we can reallocate this
+ * structure without changing the base address (a crucial feature if
+ * read actions are to go on unlocked while other entries in the BBP
+ * may be modified).
*/
@h
#define BBP_status_set(bid, mode, nme) { \
@@ -389,9 +402,9 @@ BBPinithash(void)
}
/*
- * @-
- * BBPextend must take the trimlock, as it is called when other BBP locks are
- * held and it will allocate memory. This could trigger a BBPtrim, causing
deadlock.
+ * BBPextend must take the trimlock, as it is called when other BBP
+ * locks are held and it will allocate memory. This could trigger a
+ * BBPtrim, causing deadlock.
*/
void
BBPextend(dbl factor, int buildhash)
@@ -850,9 +863,9 @@ fixstrheap(void)
#endif
/*
- * @-
- * A read only BAT can be shared in a file system by reading its descriptor
separately.
- * The default src=0 is to read the full BBPdir file.
+ * A read only BAT can be shared in a file system by reading its
+ * descriptor separately. The default src=0 is to read the full
+ * BBPdir file.
*/
static BATstore *
BBPreadEntries(FILE *fp, char *src, int *min_stamp, int *max_stamp, int
oidsize)
@@ -1151,12 +1164,12 @@ BBPheader(FILE *fp, int *BBPlimit, oid *
return bbpversion;
}
/*
- * @-
- * In a distributed version of MonetDB, it would be nice to easily share the
BATs
- * with other server instances. Although concurrency control issues should be
handled
- * with care, it can avoid excessive communication costs. The BBPimportEntry
creates
- * a BATdescriptor using symbolic links to its source. Presumably this would
lead
- * to a transparent behavior.
+ * In a distributed version of MonetDB, it would be nice to easily
+ * share the BATs with other server instances. Although concurrency
+ * control issues should be handled with care, it can avoid excessive
+ * communication costs. The BBPimportEntry creates a BATdescriptor
+ * using symbolic links to its source. Presumably this would lead to a
+ * transparent behavior.
*/
@= linkHeap
if (lstat(@3, &st) < 0) {
@@ -1419,12 +1432,11 @@ BBPinit(void)
}
/*
- * @-
- * During the exit phase all non-persistent BATs are removed.
- * Upon exit the status of the BBP tables is saved on disk.
- * This function is called once and during the shutdown of the
- * server. Since shutdown may be issued from any thread (dangerous)
- * it may lead to interference in a parallel session.
+ * During the exit phase all non-persistent BATs are removed. Upon
+ * exit the status of the BBP tables is saved on disk. This function
+ * is called once and during the shutdown of the server. Since
+ * shutdown may be issued from any thread (dangerous) it may lead to
+ * interference in a parallel session.
*/
void
@@ -1500,12 +1512,12 @@ BBPexit(void)
}
/*
- * @-
- * The routine BBPdir creates the BAT pool dictionary file.
- * It includes some information about the current state of affair in the pool.
- * The location in the buffer pool is saved for later use as well.
- * This is merely done for ease of debugging and of no importance to
front-ends.
- * The tail of non-used entries is reclaimed as well.
+ * The routine BBPdir creates the BAT pool dictionary file. It
+ * includes some information about the current state of affair in the
_______________________________________________
Checkin-list mailing list
[email protected]
http://mail.monetdb.org/mailman/listinfo/checkin-list
