ubik-doxygen-20081121
authorAdam Vollrath <axisofentropy@gmail.com>
Fri, 21 Nov 2008 07:09:42 +0000 (07:09 +0000)
committerDerrick Brashear <shadow@dementia.org>
Fri, 21 Nov 2008 07:09:42 +0000 (07:09 +0000)
LICENSE IPL10
FIXES 123681

restyle comments in ubik to be doxygen qt-style

14 files changed:
src/ubik/beacon.c
src/ubik/disk.c
src/ubik/lock.c
src/ubik/phys.c
src/ubik/recovery.c
src/ubik/remote.c
src/ubik/ubik.c
src/ubik/ubik.p.h
src/ubik/ubikclient.c
src/ubik/ubikcmd.c
src/ubik/udebug.c
src/ubik/uinit.c
src/ubik/utst_server.c
src/ubik/vote.c

index cab8595..9a996c7 100644 (file)
@@ -40,13 +40,14 @@ RCSID
 #include "ubik.h"
 #include "ubik_int.h"
 
-/* statics used to determine if we're the sync site */
-static afs_int32 syncSiteUntil = 0;    /* valid only if amSyncSite */
-int ubik_amSyncSite = 0;       /* flag telling if I'm sync site */
-static nServers;               /* total number of servers */
-static char amIMagic = 0;      /* is this host the magic host */
-char amIClone = 0;             /* is this a clone which doesn't vote */
+/*! \name statics used to determine if we're the sync site */
+static afs_int32 syncSiteUntil = 0;    /*!< valid only if amSyncSite */
+int ubik_amSyncSite = 0;       /*!< flag telling if I'm sync site */
+static nServers;               /*!< total number of servers */
+static char amIMagic = 0;      /*!< is this host the magic host */
+char amIClone = 0;             /*!< is this a clone which doesn't vote */
 static char ubik_singleServer = 0;
+/*\}*/
 int (*ubik_CRXSecurityProc) ();
 char *ubik_CRXSecurityRock;
 afs_int32 ubikSecIndex;
@@ -54,7 +55,8 @@ struct rx_securityClass *ubikSecClass;
 static verifyInterfaceAddress();
 
 
-/* Module responsible for both deciding if we're currently the sync site,
+/*! \file
+ * Module responsible for both deciding if we're currently the sync site,
  * and keeping collecting votes so as to stay sync site.
  *
  * The basic module contacts all of the servers it can, trying to get them to vote
@@ -76,7 +78,7 @@ static verifyInterfaceAddress();
  * votes and decides for how long it is the synchronization site.
  */
 
-/* procedure called from debug rpc call to get this module's state for debugging */
+/*! \brief procedure called from debug rpc call to get this module's state for debugging */
 void
 ubeacon_Debug(aparm)
      register struct ubik_debug *aparm;
@@ -86,16 +88,21 @@ ubeacon_Debug(aparm)
     aparm->nServers = nServers;
 }
 
-/* procedure that determines whether this site has enough current votes to remain sync site.
- *  called from higher-level modules (everything but the vote module).
+/*!
+ * \brief Procedure that determines whether this site has enough current votes to remain sync site.
  *
- * If we're the sync site, check that our guarantees, obtained by the ubeacon_Interact
+ * Called from higher-level modules (everything but the vote module).
+ *
+ * If we're the sync site, check that our guarantees, obtained by the ubeacon_Interact()
  * light-weight process, haven't expired.  We're sync site as long as a majority of the
- * servers in existence have promised us unexpired guarantees.  The variable ubik_syncSiteUntil
+ * servers in existence have promised us unexpired guarantees.  The variable #ubik_syncSiteUntil
  * contains the time at which the latest of the majority of the sync site guarantees expires
- * (if the variable ubik_amSyncSite is true)
+ * (if the variable #ubik_amSyncSite is true)
  * This module also calls up to the recovery module if it thinks that the recovery module
- * may have to pick up a new database (which offucr sif we lose the sync site votes).
+ * may have to pick up a new database (which offucr sif [sic] we lose the sync site votes).
+ *
+ * \return 1 if local site is the sync site
+ * \return 0 if sync site is elsewhere
  */
 ubeacon_AmSyncSite()
 {
@@ -126,20 +133,8 @@ ubeacon_AmSyncSite()
     return rcode;
 }
 
-/* setup server list; called with two parms, first is my address, second is list of other servers
- * called only at initialization to set up the list of servers to contact for votes.  Just creates
- * the server structure.  Note that there are two connections in every server structure, one for
- * vote calls (which must always go through quickly) and one for database operations, which
- * are subject to waiting for locks.  If we used only one, the votes would sometimes get
- * held up behind database operations, and the sync site guarantees would timeout
- * even though the host would be up for communication.
- *
- * The "magic" host is the one with the lowest internet address.  It is
- * magic because its vote counts epsilon more than the others.  This acts
- * as a tie-breaker when we have an even number of hosts in the system.
- * For example, if the "magic" host is up in a 2 site system, then it
- * is sync site.  Without the magic host hack, if anyone crashed in a 2
- * site system, we'd be out of business.
+/*!
+ * \see ubeacon_InitServerListCommon()
  */
 ubeacon_InitServerListByInfo(ame, info, clones)
      afs_int32 ame;
@@ -152,6 +147,12 @@ ubeacon_InitServerListByInfo(ame, info, clones)
     return code;
 }
 
+/*!
+ * \param ame "address of me"
+ * \param aservers list of other servers
+ *
+ * \see ubeacon_InitServerListCommon()
+ */
 ubeacon_InitServerList(ame, aservers)
      afs_int32 ame;
      register afs_int32 aservers[];
@@ -164,6 +165,30 @@ ubeacon_InitServerList(ame, aservers)
     return code;
 }
 
+/*!
+ * \brief setup server list
+ *
+ * \param ame "address of me"
+ * \param aservers list of other servers
+ *
+ * called only at initialization to set up the list of servers to contact for votes.  Just creates
+ * the server structure.  
+ *
+ * The "magic" host is the one with the lowest internet address.  It is
+ * magic because its vote counts epsilon more than the others.  This acts
+ * as a tie-breaker when we have an even number of hosts in the system.
+ * For example, if the "magic" host is up in a 2 site system, then it
+ * is sync site.  Without the magic host hack, if anyone crashed in a 2
+ * site system, we'd be out of business.
+ *
+ * \note There are two connections in every server structure, one for
+ * vote calls (which must always go through quickly) and one for database operations, which
+ * are subject to waiting for locks.  If we used only one, the votes would sometimes get
+ * held up behind database operations, and the sync site guarantees would timeout
+ * even though the host would be up for communication.
+ *
+ * \see ubeacon_InitServerList(), ubeacon_InitServerListByInfo()
+ */
 ubeacon_InitServerListCommon(ame, info, clones, aservers)
      afs_int32 ame;
      struct afsconf_cell *info;
@@ -301,9 +326,11 @@ ubeacon_InitServerListCommon(ame, info, clones, aservers)
     return 0;
 }
 
-/* main lwp loop for code that sends out beacons.  This code only runs while
- * we're sync site or we want to be the sync site.  It runs in its very own light-weight
- * process.
+/*! 
+ * \brief main lwp loop for code that sends out beacons.
+ * 
+ * This code only runs while we're sync site or we want to be the sync site.
+ * It runs in its very own light-weight process.
  */
 void *
 ubeacon_Interact(void *dummy)
@@ -466,20 +493,23 @@ ubeacon_Interact(void *dummy)
     return NULL;
 }
 
-/* 
-* Input Param   : ame is the pointer to my IP address specified in the
-*                 CellServDB file. aservers is an array containing IP 
-*                 addresses of remote ubik servers. The array is 
-*                 terminated by a zero address.
-*
-* Algorithm     : Verify that my IP addresses 'ame' does actually exist
-*                 on this machine.  If any of my IP addresses are there 
-*                 in the remote server list 'aserver', remove them from 
-*                 this list.  Update global variable ubik_host[] with 
-*                 my IP addresses.
-*
-* Return Values : 0 on success, non-zero on failure
-*/
+/*!
+ * \brief Verify that a given IP addresses does actually exist on this machine.
+ *
+ * \param ame      the pointer to my IP address specified in the
+ *                 CellServDB file. 
+ * \param aservers an array containing IP 
+ *                 addresses of remote ubik servers. The array is 
+ *                 terminated by a zero address.
+ *
+ * Algorithm     : Verify that my IP addresses \p ame does actually exist
+ *                 on this machine.  If any of my IP addresses are there 
+ *                 in the remote server list \p aserver, remove them from 
+ *                 this list.  Update global variable \p ubik_host[] with 
+ *                 my IP addresses.
+ *
+ * \return 0 on success, non-zero on failure
+ */
 static
 verifyInterfaceAddress(ame, info, aservers)
      afs_uint32 *ame;          /* one of my interface addr in net byte order */
@@ -621,15 +651,17 @@ verifyInterfaceAddress(ame, info, aservers)
 }
 
 
-/* 
-* Input Param   : ubik_host is an array containing all my IP addresses.
-*
-* Algorithm     : Do an RPC to all remote ubik servers infroming them 
-*                 about my IP addresses. Get their IP addresses and
-*                 update my linked list of ubik servers 'ubik_servers'
-*
-* Return Values : 0 on success, non-zero on failure
-*/
+/*! 
+ * \brief Exchange IP address information with remote servers.
+ *
+ * \param ubik_host an array containing all my IP addresses.
+ *
+ * Algorithm     : Do an RPC to all remote ubik servers infroming them 
+ *                 about my IP addresses. Get their IP addresses and
+ *                 update my linked list of ubik servers \p ubik_servers
+ *
+ * \return 0 on success, non-zero on failure
+ */
 int
 updateUbikNetworkAddress(ubik_host)
      afs_uint32 ubik_host[UBIK_MAX_INTERFACE_ADDR];
index a32f7c5..9ad89f8 100644 (file)
@@ -33,22 +33,22 @@ RCSID
 
 #define        PHSIZE  128
 static struct buffer {
-    struct ubik_dbase *dbase;  /* dbase within which the buffer resides */
-    afs_int32 file;            /* Unique cache key */
-    afs_int32 page;            /* page number */
+    struct ubik_dbase *dbase;  /*!< dbase within which the buffer resides */
+    afs_int32 file;            /*!< Unique cache key */
+    afs_int32 page;            /*!< page number */
     struct buffer *lru_next;
     struct buffer *lru_prev;
-    struct buffer *hashNext;   /* next dude in hash table */
-    char *data;                        /* ptr to the data */
-    char lockers;              /* usage ref count */
-    char dirty;                        /* is buffer modified */
-    char hashIndex;            /* back ptr to hash table */
+    struct buffer *hashNext;   /*!< next dude in hash table */
+    char *data;                        /*!< ptr to the data */
+    char lockers;              /*!< usage ref count */
+    char dirty;                        /*!< is buffer modified */
+    char hashIndex;            /*!< back ptr to hash table */
 } *Buffers;
 
 #define pHash(page) ((page) & (PHSIZE-1))
 
 afs_int32 ubik_nBuffers = NBUFFERS;
-static struct buffer *phTable[PHSIZE]; /* page hash table */
+static struct buffer *phTable[PHSIZE]; /*!< page hash table */
 static struct buffer *LruBuffer;
 static int nbuffers;
 static int calls = 0, ios = 0, lastb = 0;
@@ -62,7 +62,9 @@ static DTrunc(struct ubik_dbase *dbase, afs_int32 fid, afs_int32 length);
 
 static struct ubik_trunc *freeTruncList = 0;
 
-/* remove a transaction from the database's active transaction list.  Don't free it */
+/*!
+ * \brief Remove a transaction from the database's active transaction list.  Don't free it.
+ */
 static int
 unthread(struct ubik_trans *atrans)
 {
@@ -78,7 +80,9 @@ unthread(struct ubik_trans *atrans)
     return 2;                  /* no entry */
 }
 
-/* some debugging assistance */
+/*!
+ * \brief some debugging assistance
+ */
 int
 udisk_Debug(struct ubik_debug *aparm)
 {
@@ -100,20 +104,21 @@ udisk_Debug(struct ubik_debug *aparm)
     return 0;
 }
 
-/* log format is defined here, and implicitly in recovery.c
+/*!
+ * \brief Write an opcode to the log.
+ *
+ * log format is defined here, and implicitly in recovery.c
  *
  * 4 byte opcode, followed by parameters, each 4 bytes long.  All integers
  * are in logged in network standard byte order, in case we want to move logs
  * from machine-to-machine someday.
  *
- * Begin transaction: opcode
- * Commit transaction: opcode, version (8 bytes)
- * Truncate file: opcode, file number, length
- * Abort transaction: opcode
- * Write data: opcode, file, position, length, <length> data bytes
+ * Begin transaction: opcode \n
+ * Commit transaction: opcode, version (8 bytes) \n
+ * Truncate file: opcode, file number, length \n
+ * Abort transaction: opcode \n
+ * Write data: opcode, file, position, length, <length> data bytes \n
  */
-
-/* write an opcode to the log */
 int
 udisk_LogOpcode(struct ubik_dbase *adbase, afs_int32 aopcode, int async)
 {
@@ -141,7 +146,9 @@ udisk_LogOpcode(struct ubik_dbase *adbase, afs_int32 aopcode, int async)
     return code;
 }
 
-/* log a commit, never syncing */
+/*!
+ * \brief Log a commit, never syncing.
+ */
 int
 udisk_LogEnd(struct ubik_dbase *adbase, struct ubik_version *aversion)
 {
@@ -171,7 +178,9 @@ udisk_LogEnd(struct ubik_dbase *adbase, struct ubik_version *aversion)
     return code;
 }
 
-/* log a truncate operation, never syncing */
+/*!
+ * \brief Log a truncate operation, never syncing.
+ */
 int
 udisk_LogTruncate(struct ubik_dbase *adbase, afs_int32 afile,
                  afs_int32 alength)
@@ -199,7 +208,9 @@ udisk_LogTruncate(struct ubik_dbase *adbase, afs_int32 afile,
     return 0;
 }
 
-/* write some data to the log, never syncing */
+/*!
+ * \brief Write some data to the log, never syncing.
+ */
 int
 udisk_LogWriteData(struct ubik_dbase *adbase, afs_int32 afile, char *abuffer,
                   afs_int32 apos, afs_int32 alen)
@@ -261,7 +272,9 @@ DInit(int abuffers)
     return 0;
 }
 
-/* Take a buffer and mark it as the least recently used buffer */
+/*!
+ * \brief Take a buffer and mark it as the least recently used buffer.
+ */
 static void
 Dlru(struct buffer *abuf)
 {
@@ -281,7 +294,9 @@ Dlru(struct buffer *abuf)
     LruBuffer = abuf;
 }
 
-/* Take a buffer and mark it as the most recently used buffer */
+/*!
+ * \brief Take a buffer and mark it as the most recently used buffer.
+ */
 static void
 Dmru(struct buffer *abuf)
 {
@@ -301,7 +316,9 @@ Dmru(struct buffer *abuf)
     LruBuffer->lru_prev = abuf;
 }
 
-/* get a pointer to a particular buffer */
+/*!
+ * \brief Get a pointer to a particular buffer.
+ */
 static char *
 DRead(struct ubik_dbase *dbase, afs_int32 fid, int page)
 {
@@ -351,7 +368,9 @@ DRead(struct ubik_dbase *dbase, afs_int32 fid, int page)
     return tb->data;
 }
 
-/* zap truncated pages */
+/*!
+ * \brief Zap truncated pages.
+ */
 static int
 DTrunc(struct ubik_dbase *dbase, afs_int32 fid, afs_int32 length)
 {
@@ -369,10 +388,13 @@ DTrunc(struct ubik_dbase *dbase, afs_int32 fid, afs_int32 length)
     return 0;
 }
 
-/* allocate a truncation entry.  We allocate special entries representing truncations, rather than
-    performing them immediately, so that we can abort a transaction easily by simply purging
-    the in-core memory buffers and discarding these truncation entries.
-*/
+/*!
+ * \brief Allocate a truncation entry.
+ *
+ * We allocate special entries representing truncations, rather than
+ * performing them immediately, so that we can abort a transaction easily by simply purging
+ * the in-core memory buffers and discarding these truncation entries.
+ */
 static struct ubik_trunc *
 GetTrunc(void)
 {
@@ -387,7 +409,9 @@ GetTrunc(void)
     return tt;
 }
 
-/* free a truncation entry */
+/*!
+ * \brief Free a truncation entry.
+ */
 static int
 PutTrunc(struct ubik_trunc *at)
 {
@@ -396,7 +420,9 @@ PutTrunc(struct ubik_trunc *at)
     return 0;
 }
 
-/* find a truncation entry for a file, if any */
+/*!
+ * \brief Find a truncation entry for a file, if any.
+ */
 static struct ubik_trunc *
 FindTrunc(struct ubik_trans *atrans, afs_int32 afile)
 {
@@ -408,7 +434,9 @@ FindTrunc(struct ubik_trans *atrans, afs_int32 afile)
     return (struct ubik_trunc *)0;
 }
 
-/* do truncates associated with trans, and free them */
+/*!
+ * \brief Do truncates associated with \p atrans, and free them.
+ */
 static int
 DoTruncs(struct ubik_trans *atrans)
 {
@@ -430,7 +458,9 @@ DoTruncs(struct ubik_trans *atrans)
     return (rcode);
 }
 
-/* mark a fid as invalid */
+/*!
+ * \brief Mark an \p fid as invalid.
+ */
 int
 udisk_Invalidate(struct ubik_dbase *adbase, afs_int32 afid)
 {
@@ -446,7 +476,9 @@ udisk_Invalidate(struct ubik_dbase *adbase, afs_int32 afid)
     return 0;
 }
 
-/* move this page into the correct hash bucket */
+/*!
+ * \brief Move this page into the correct hash bucket.
+ */
 static int
 FixupBucket(struct buffer *ap)
 {
@@ -470,7 +502,9 @@ FixupBucket(struct buffer *ap)
     return 0;
 }
 
-/* create a new slot for a particular dbase page */
+/*!
+ * \brief Create a new slot for a particular dbase page.
+ */
 static struct buffer *
 newslot(struct ubik_dbase *adbase, afs_int32 afid, afs_int32 apage)
 {
@@ -503,7 +537,9 @@ newslot(struct ubik_dbase *adbase, afs_int32 afid, afs_int32 apage)
     return pp;
 }
 
-/* Release a buffer, specifying whether or not the buffer has been modified by the locker. */
+/*!
+ * \brief Release a buffer, specifying whether or not the buffer has been modified by the locker.
+ */
 static void
 DRelease(char *ap, int flag)
 {
@@ -520,9 +556,12 @@ DRelease(char *ap, int flag)
     return;
 }
 
-/* flush all modified buffers, leaves dirty bits set (they're cleared
- * by DSync).  Note interaction with DSync: you call this thing first,
- * writing the buffers to the disk.  Then you call DSync to sync all the
+/*!
+ * \brief Flush all modified buffers, leaves dirty bits set (they're cleared
+ * by DSync()).  
+ *
+ * \note Note interaction with DSync(): you call this thing first,
+ * writing the buffers to the disk.  Then you call DSync() to sync all the
  * files that were written, and to clear the dirty bits.  You should
  * always call DFlush/DSync as a pair.
  */
@@ -547,7 +586,9 @@ DFlush(struct ubik_dbase *adbase)
     return 0;
 }
 
-/* flush all modified buffers */
+/*!
+ * \brief Flush all modified buffers.
+ */
 static int
 DAbort(struct ubik_dbase *adbase)
 {
@@ -565,7 +606,9 @@ DAbort(struct ubik_dbase *adbase)
     return 0;
 }
 
-/* must only be called after DFlush, due to its interpretation of dirty flag */
+/*!
+ * \attention DSync() must only be called after DFlush(), due to its interpretation of dirty flag.
+ */
 static int
 DSync(struct ubik_dbase *adbase)
 {
@@ -596,7 +639,9 @@ DSync(struct ubik_dbase *adbase)
     return rCode;
 }
 
-/* Same as read, only do not even try to read the page */
+/*!
+ * \brief Same as DRead(), only do not even try to read the page.
+ */
 static char *
 DNew(struct ubik_dbase *dbase, afs_int32 fid, int page)
 {
@@ -609,7 +654,9 @@ DNew(struct ubik_dbase *dbase, afs_int32 fid, int page)
     return tb->data;
 }
 
-/* read data from database */
+/*!
+ * \brief Read data from database.
+ */
 int
 udisk_read(struct ubik_trans *atrans, afs_int32 afile, char *abuffer,
           afs_int32 apos, afs_int32 alen)
@@ -641,7 +688,9 @@ udisk_read(struct ubik_trans *atrans, afs_int32 afile, char *abuffer,
     return 0;
 }
 
-/* truncate file */
+/*!
+ * \brief Truncate file.
+ */
 int
 udisk_truncate(struct ubik_trans *atrans, afs_int32 afile, afs_int32 alength)
 {
@@ -673,7 +722,9 @@ udisk_truncate(struct ubik_trans *atrans, afs_int32 afile, afs_int32 alength)
     return code;
 }
 
-/* write data to database, using logs */
+/*!
+ * \brief Write data to database, using logs.
+ */
 int
 udisk_write(struct ubik_trans *atrans, afs_int32 afile, char *abuffer,
            afs_int32 apos, afs_int32 alen)
@@ -728,7 +779,9 @@ udisk_write(struct ubik_trans *atrans, afs_int32 afile, char *abuffer,
     return 0;
 }
 
-/* begin a new local transaction */
+/*!
+ * \brief Begin a new local transaction.
+ */
 int
 udisk_begin(struct ubik_dbase *adbase, int atype, struct ubik_trans **atrans)
 {
@@ -762,7 +815,9 @@ udisk_begin(struct ubik_dbase *adbase, int atype, struct ubik_trans **atrans)
     return 0;
 }
 
-/* commit transaction */
+/*!
+ * \brief Commit transaction.
+ */
 int
 udisk_commit(struct ubik_trans *atrans)
 {
@@ -841,7 +896,9 @@ udisk_commit(struct ubik_trans *atrans)
     return code;
 }
 
-/* abort transaction */
+/*!
+ * \brief Abort transaction.
+ */
 int
 udisk_abort(struct ubik_trans *atrans)
 {
@@ -874,8 +931,10 @@ udisk_abort(struct ubik_trans *atrans)
     return 0;
 }
 
-/* destroy a transaction after it has been committed or aborted.  if
- * it hasn't committed before you call this routine, we'll abort the
+/*!
+ * \brief Destroy a transaction after it has been committed or aborted.
+ *
+ * If it hasn't committed before you call this routine, we'll abort the
  * transaction for you.
  */
 int
index 06c6f1a..43d3e47 100644 (file)
@@ -25,7 +25,8 @@ RCSID
 #include "ubik.h"
 #include "ubik_int.h"
 
-/* Locks hang off of each transaction, with all the transaction hanging off of
+/*! \file
+ * Locks hang off of each transaction, with all the transaction hanging off of
  * the appropriate dbase.  This package expects to be used in a two-phase locking
  * protocol, so it doesn't provide a way to release anything but all of the locks in the
  * transaction.
@@ -36,12 +37,12 @@ RCSID
  *
  * It is the responsibility of the user to avoid deadlock by setting locks in a partial order.
  *
- * EWOULDBLOCK has been replaced in this file by EAGAIN. Many Unix's but not
- * all (eg. HP) do not replace EWOULDBLOCK with EAGAIN. The bad news is this
+ * #EWOULDBLOCK has been replaced in this file by #EAGAIN. Many Unix's but not
+ * all (eg. HP) do not replace #EWOULDBLOCK with #EAGAIN. The bad news is this
  * goes over the wire. The good news is that the code path is never triggered
  * as it requires ulock_getLock to be called with await = 0. And ulock_SetLock
  * isn't even used in this code base. Since NT doesn't have a native
- * EAGAIN, we are replacing all instances of EWOULDBLOCK with EAGAIN.
+ * #EAGAIN, we are replacing all instances of #EWOULDBLOCK with #EAGAIN.
  * 
  */
 
@@ -53,11 +54,13 @@ RCSID
 struct Lock rwlock;
 int rwlockinit = 1;
 
-/* Set a transaction lock.  Atype is LOCKREAD or LOCKWRITE, await is
- * true if you want to wait for the lock instead of returning
- * EWOULDLBOCK.
+/*!
+ * \brief Set a transaction lock.
+ * \param atype is #LOCKREAD or #LOCKWRITE.
+ * \param await is TRUE if you want to wait for the lock instead of returning
+ * #EWOULDBLOCK.
  *
- * The DBHOLD lock must be held.
+ * \note The #DBHOLD lock must be held.
  */
 ulock_getLock(atrans, atype, await)
      struct ubik_trans *atrans;
@@ -144,7 +147,9 @@ ulock_getLock(atrans, atype, await)
     return 0;
 }
 
-/* Release the transaction lock */
+/*!
+ * \brief Release the transaction lock.
+ */
 void
 ulock_relLock(atrans)
      struct ubik_trans *atrans;
@@ -167,7 +172,9 @@ ulock_relLock(atrans)
     return;
 }
 
-/* debugging hooks */
+/*!
+ * \brief debugging hooks
+ */
 ulock_Debug(aparm)
      struct ubik_debug *aparm;
 {
index 636a6a3..99b2edf 100644 (file)
@@ -38,8 +38,9 @@ RCSID
 #define        UBIK_INTERNALS 1
 #include "ubik.h"
 
-/* these routines are called via the proc ptr in the ubik_dbase structure.  They provide access to
- * the physical disk, by converting the file numbers being processed (>= 0 for user data space, < 0
+/*! \file
+ * These routines are called via the proc ptr in the ubik_dbase structure.  They provide access to
+ * the physical disk, by converting the file numbers being processed ( >= 0 for user data space, < 0
  * for ubik system files, such as the log) to actual pathnames to open, read, write, truncate, sync,
  * etc.
  */
@@ -53,7 +54,9 @@ static struct fdcache {
 
 static char pbuffer[1024];
 
-/* beware, when using this function, of the header in front of most files */
+/*!
+ * \warning Beware, when using this function, of the header in front of most files.
+ */
 static int
 uphys_open(register struct ubik_dbase *adbase, afs_int32 afid)
 {
@@ -126,7 +129,9 @@ uphys_open(register struct ubik_dbase *adbase, afs_int32 afid)
     return fd;
 }
 
-/* close the file, maintaining ref count in cache structure */
+/*!
+ * \brief Close the file, maintaining ref count in cache structure.
+ */
 int
 uphys_close(register int afd)
 {
@@ -238,7 +243,11 @@ uphys_truncate(register struct ubik_dbase *adbase, afs_int32 afile,
     return code;
 }
 
-/* get number of dbase files */
+/*!
+ * \brief Get number of dbase files.
+ *
+ * \todo Really should scan dir for data.
+ */
 int
 uphys_getnfiles(register struct ubik_dbase *adbase)
 {
@@ -246,7 +255,9 @@ uphys_getnfiles(register struct ubik_dbase *adbase)
     return 1;
 }
 
-/* get database label, with aversion in host order */
+/*!
+ * \brief Get database label, with \p aversion in host order.
+ */
 int
 uphys_getlabel(register struct ubik_dbase *adbase, afs_int32 afile,
               struct ubik_version *aversion)
@@ -268,7 +279,9 @@ uphys_getlabel(register struct ubik_dbase *adbase, afs_int32 afile,
     return 0;
 }
 
-/* label database, with aversion in host order */
+/*!
+ * \brief Label database, with \p aversion in host order.
+ */
 int
 uphys_setlabel(register struct ubik_dbase *adbase, afs_int32 afile,
               struct ubik_version *aversion)
index ae3a7ee..a6293e5 100644 (file)
@@ -35,24 +35,23 @@ RCSID
 #include "ubik.h"
 #include "ubik_int.h"
 
-/* This module is responsible for determining when the system has
+/*! \file
+ * This module is responsible for determining when the system has
  * recovered to the point that it can handle new transactions.  It
  * replays logs, polls to determine the current dbase after a crash,
  * and distributes the new database to the others.
- */
-
-/* The sync site associates a version number with each database.  It
+ *
+ * The sync site associates a version number with each database.  It
  * broadcasts the version associated with its current dbase in every
  * one of its beacon messages.  When the sync site send a dbase to a
  * server, it also sends the db's version.  A non-sync site server can
  * tell if it has the right dbase version by simply comparing the
- * version from the beacon message (uvote_dbVersion) with the version
- * associated with the database (ubik_dbase->version).  The sync site
+ * version from the beacon message \p uvote_dbVersion with the version
+ * associated with the database \p ubik_dbase->version.  The sync site
  * itself simply has one counter to keep track of all of this (again
- * ubik_dbase->version).
- */
-
-/* sync site: routine called when the sync site loses its quorum; this
+ * \p ubik_dbase->version).
+ *
+ * sync site: routine called when the sync site loses its quorum; this
  * procedure is called "up" from the beacon package.  It resyncs the
  * dbase and nudges the recovery daemon to try to propagate out the
  * changes.  It also resets the recovery daemon's state, since
@@ -61,11 +60,12 @@ RCSID
  * servers.
  */
 
-/* if this flag is set, then ubik will use only the primary address 
-** ( the address specified in the CellServDB) to contact other 
-** ubik servers. Ubik recovery will not try opening connections 
-** to the alternate interface addresses. 
-*/
+/*!
+ * if this flag is set, then ubik will use only the primary address 
+ * (the address specified in the CellServDB) to contact other 
+ * ubik servers. Ubik recovery will not try opening connections 
+ * to the alternate interface addresses. 
+ */
 int ubikPrimaryAddrOnly;
 
 int
@@ -79,9 +79,13 @@ urecovery_ResetState(void)
     return 0;
 }
 
-/* sync site: routine called when a non-sync site server goes down; restarts recovery
+/*!
+ * \brief sync site
+ *
+ * routine called when a non-sync site server goes down; restarts recovery
  * process to send missing server the new db when it comes back up.
- * This routine should not do anything with variables used by non-sync site servers. 
+ *
+ * \note This routine should not do anything with variables used by non-sync site servers. 
  */
 int
 urecovery_LostServer(void)
@@ -93,7 +97,8 @@ urecovery_LostServer(void)
 #endif
 }
 
-/* return true iff we have a current database (called by both sync
+/*!
+ * return true iff we have a current database (called by both sync
  * sites and non-sync sites) How do we determine this?  If we're the
  * sync site, we wait until recovery has finished fetching and
  * re-labelling its dbase (it may still be trying to propagate it out
@@ -133,7 +138,9 @@ urecovery_AllBetter(register struct ubik_dbase *adbase, int areadAny)
     return rcode;
 }
 
-/* abort all transactions on this database */
+/*!
+ * \brief abort all transactions on this database
+ */
 int
 urecovery_AbortAll(struct ubik_dbase *adbase)
 {
@@ -144,7 +151,9 @@ urecovery_AbortAll(struct ubik_dbase *adbase)
     return 0;
 }
 
-/* this routine aborts the current remote transaction, if any, if the tid is wrong */
+/*!
+ * \brief this routine aborts the current remote transaction, if any, if the tid is wrong
+ */
 int
 urecovery_CheckTid(register struct ubik_tid *atid)
 {
@@ -168,17 +177,20 @@ urecovery_CheckTid(register struct ubik_tid *atid)
     return 0;
 }
 
-/* log format is defined here, and implicitly in disk.c
+/*!
+ * \brief replay logs
+ *
+ * log format is defined here, and implicitly in disk.c
  *
  * 4 byte opcode, followed by parameters, each 4 bytes long.  All integers
  * are in logged in network standard byte order, in case we want to move logs
  * from machine-to-machine someday.
  *
- * Begin transaction: opcode
- * Commit transaction: opcode, version (8 bytes)
- * Truncate file: opcode, file number, length
- * Abort transaction: opcode
- * Write data: opcode, file, position, length, <length> data bytes
+ * Begin transaction: opcode \n
+ * Commit transaction: opcode, version (8 bytes) \n
+ * Truncate file: opcode, file number, length \n
+ * Abort transaction: opcode \n
+ * Write data: opcode, file, position, length, <length> data bytes \n
  *
  * A very simple routine, it just replays the log.  Note that this is a new-value only log, which
  * implies that no uncommitted data is written to the dbase: one writes data to the log, including
@@ -189,8 +201,6 @@ urecovery_CheckTid(register struct ubik_tid *atid)
  * abort and the remaining dbase on the disk is exactly the right dbase, without having to read
  * the log.
  */
-
-/* replay logs */
 static int
 ReplayLog(register struct ubik_dbase *adbase)
 {
@@ -349,7 +359,9 @@ ReplayLog(register struct ubik_dbase *adbase)
     return code;
 }
 
-/* Called at initialization to figure out version of the dbase we really have.
+/*! \brief
+ * Called at initialization to figure out version of the dbase we really have.
+ *
  * This routine is called after replaying the log; it reads the restored labels.
  */
 static int
@@ -378,7 +390,9 @@ InitializeDB(register struct ubik_dbase *adbase)
     return 0;
 }
 
-/* initialize the local dbase
+/*!
+ * \brief initialize the local ubik_dbase
+ *
  * We replay the logs and then read the resulting file to figure out what version we've really got.
  */
 int
@@ -393,12 +407,14 @@ urecovery_Initialize(register struct ubik_dbase *adbase)
     return code;
 }
 
-/* Main interaction loop for the recovery manager
+/*!
+ * \brief Main interaction loop for the recovery manager
+ *
  * The recovery light-weight process only runs when you're the
  * synchronization site.  It performs the following tasks, if and only
  * if the prerequisite tasks have been performed successfully (it
  * keeps track of which ones have been performed in its bit map,
- * urecovery_state).
+ * \p urecovery_state).
  *
  * First, it is responsible for probing that all servers are up.  This
  * is the only operation that must be performed even if this is not
@@ -838,10 +854,11 @@ urecovery_Interact(void *dummy)
     return NULL;
 }
 
-/*
-** send a Probe to all the network address of this server 
-** Return 0  if success, else return 1
-*/
+/*!
+ * \brief send a Probe to all the network address of this server 
+ * 
+ * \return 0 if success, else return 1
+ */
 int
 DoProbe(struct ubik_server *server)
 {
index 56b4c88..804fb7b 100644 (file)
@@ -35,10 +35,11 @@ int (*ubik_CheckRXSecurityProc) ();
 char *ubik_CheckRXSecurityRock;
 void printServerInfo();
 
-/* routines for handling requests remotely-submitted by the sync site.  These are
-    only write transactions (we don't propagate read trans), and there is at most one
-    write transaction extant at any one time.
-*/
+/*! \file
+ * routines for handling requests remotely-submitted by the sync site.  These are
+ * only write transactions (we don't propagate read trans), and there is at most one
+ * write transaction extant at any one time.
+ */
 
 struct ubik_trans *ubik_currentTrans = 0;
 
@@ -261,7 +262,9 @@ SDISK_Lock(rxcall, atid, afile, apos, alen, atype)
     return code;
 }
 
-/* Write a vector of data */
+/*!
+ * \brief Write a vector of data
+ */
 afs_int32
 SDISK_WriteV(rxcall, atid, io_vector, io_buffer)
      register struct rx_call *rxcall;
@@ -661,11 +664,12 @@ SDISK_Probe(rxcall)
     return 0;
 }
 
-/*
-* Update remote machines addresses in my server list
-* Send back my addresses to caller of this RPC
-* Returns zero on success, else 1.
-*/
+/*!
+ * \brief Update remote machines addresses in my server list
+ *
+ * Send back my addresses to caller of this RPC
+ * \return zero on success, else 1.
+ */
 afs_int32
 SDISK_UpdateInterfaceAddr(rxcall, inAddr, outAddr)
      register struct rx_call *rxcall;
index 7d017b1..570393c 100644 (file)
@@ -36,42 +36,41 @@ RCSID
 
 #define ERROR_EXIT(code) {error=(code); goto error_exit;}
 
-/*  This system is organized in a hierarchical set of related modules.  Modules
-    at one level can only call modules at the same level or below.
-    
-    At the bottom level (0) we have R, RFTP, LWP and IOMGR, i.e. the basic
-    operating system primitives.
-    
-    At the next level (1) we have
-
-       VOTER--The module responsible for casting votes when asked.  It is also
-       responsible for determining whether this server should try to become
-       a synchronization site.
-       
-       BEACONER--The module responsible for sending keep-alives out when a
-       server is actually the sync site, or trying to become a sync site.
-       
-       DISK--The module responsible for representing atomic transactions
-       on the local disk.  It maintains a new-value only log.
-       
-       LOCK--The module responsible for locking byte ranges in the database file.
-       
-    At the next level (2) we have
-         
-       RECOVERY--The module responsible for ensuring that all members of a quorum
-       have the same up-to-date database after a new synchronization site is
-       elected.  This module runs only on the synchronization site.
-       
-    At the next level (3) we have
-    
-       REMOTE--The module responsible for interpreting requests from the sync
-       site and applying them to the database, after obtaining the appropriate
-       locks.
-       
-    At the next level (4) we have
-    
-       UBIK--The module users call to perform operations on the database.
-*/
+/*!
+ * \file
+ * This system is organized in a hierarchical set of related modules.  Modules
+ * at one level can only call modules at the same level or below.
+ * 
+ * At the bottom level (0) we have R, RFTP, LWP and IOMGR, i.e. the basic
+ * operating system primitives.
+ *
+ * At the next level (1) we have
+ *
+ * \li VOTER--The module responsible for casting votes when asked.  It is also
+ * responsible for determining whether this server should try to become
+ * a synchronization site.
+ * \li BEACONER--The module responsible for sending keep-alives out when a
+ * server is actually the sync site, or trying to become a sync site.
+ * \li DISK--The module responsible for representing atomic transactions
+ * on the local disk.  It maintains a new-value only log.
+ * \li LOCK--The module responsible for locking byte ranges in the database file.
+ *     
+ * At the next level (2) we have
+ *  
+ * \li RECOVERY--The module responsible for ensuring that all members of a quorum
+ * have the same up-to-date database after a new synchronization site is
+ * elected.  This module runs only on the synchronization site.
+ *     
+ * At the next level (3) we have
+ *
+ * \li REMOTE--The module responsible for interpreting requests from the sync
+ * site and applying them to the database, after obtaining the appropriate
+ * locks.
+ *
+ * At the next level (4) we have
+ *
+ * \li UBIK--The module users call to perform operations on the database.
+ */
 
 
 /* some globals */
@@ -90,18 +89,21 @@ static int BeginTrans();
 
 struct rx_securityClass *ubik_sc[3];
 
-/* perform an operation at a quorum, handling error conditions.  return 0 if
-    all worked, otherwise mark failing server as down and return UERROR
-
-    Note that if any server misses an update, we must wait BIGTIME seconds before
-    allowing the transaction to commit, to ensure that the missing and possibly still
-    functioning server times out and stop handing out old data.  This is done in the commit
-    code, where we wait for a server marked down to have stayed down for BIGTIME seconds
-    before we allow a transaction to commit.  A server that fails but comes back up won't give
-    out old data because it is sent the sync count along with the beacon message that
-    marks it as *really* up (beaconSinceDown).
-*/
 #define        CStampVersion       1   /* meaning set ts->version */
+
+/*! 
+ * \brief Perform an operation at a quorum, handling error conditions.
+ * \return 0 if all worked and a quorum was contacted successfully
+ * \return otherwise mark failing server as down and return #UERROR
+ *
+ * \note If any server misses an update, we must wait #BIGTIME seconds before
+ * allowing the transaction to commit, to ensure that the missing and possibly still
+ * functioning server times out and stops handing out old data.  This is done in the commit
+ * code, where we wait for a server marked down to have stayed down for #BIGTIME seconds
+ * before we allow a transaction to commit.  A server that fails but comes back up won't give
+ * out old data because it is sent the sync count along with the beacon message that
+ * marks it as \b really up (\p beaconSinceDown).
+ */
 afs_int32
 ContactQuorum(aproc, atrans, aflags, aparm0, aparm1, aparm2, aparm3, aparm4,
              aparm5)
@@ -176,11 +178,19 @@ ContactQuorum(aproc, atrans, aflags, aparm0, aparm1, aparm2, aparm3, aparm4,
        return rcode;
 }
 
-/* This routine initializes the ubik system for a set of servers.  It returns 0 for success, or an error code on failure.  The set of servers is specified by serverList; nServers gives the number of entries in this array.  Finally, dbase is the returned structure representing this instance of a ubik; it is passed to various calls below.  The variable pathName provides an initial prefix used for naming storage files used by this system.  It should perhaps be generalized to a low-level disk interface providing read, write, file enumeration and sync operations.
-
-    Note that the host named by myHost should not also be listed in serverList.
-*/
-
+/*! 
+ * \brief This routine initializes the ubik system for a set of servers.
+ * \return 0 for success, or an error code on failure.
+ * \param serverList set of servers specified; nServers gives the number of entries in this array.
+ * \param pathName provides an initial prefix used for naming storage files used by this system.  
+ * \param dbase the returned structure representing this instance of an ubik; it is passed to various calls below.  
+ *
+ * \todo This routine should perhaps be generalized to a low-level disk interface providing read, write, file enumeration and sync operations.
+ *
+ * \warning The host named by myHost should not also be listed in serverList.
+ *
+ * \see ubik_ServerInit(), ubik_ServerInitByInfo()
+ */
 int
 ubik_ServerInitCommon(afs_int32 myHost, short myPort,
                      struct afsconf_cell *info, char clones[],
@@ -354,6 +364,9 @@ ubik_ServerInitCommon(afs_int32 myHost, short myPort,
 
 }
 
+/*!
+ * \see ubik_ServerInitCommon()
+ */
 int
 ubik_ServerInitByInfo(afs_int32 myHost, short myPort,
                      struct afsconf_cell *info, char clones[],
@@ -367,6 +380,9 @@ ubik_ServerInitByInfo(afs_int32 myHost, short myPort,
     return code;
 }
 
+/*!
+ * \see ubik_ServerInitCommon()
+ */
 int
 ubik_ServerInit(afs_int32 myHost, short myPort, afs_int32 serverList[],
                char *pathName, struct ubik_dbase **dbase)
@@ -379,17 +395,18 @@ ubik_ServerInit(afs_int32 myHost, short myPort, afs_int32 serverList[],
     return code;
 }
 
-/*  This routine begins a read or write transaction on the transaction
-    identified by transPtr, in the dbase named by dbase.  An open mode of
-    ubik_READTRANS identifies this as a read transaction, while a mode of
-    ubik_WRITETRANS identifies this as a write transaction.  transPtr 
-    is set to the returned transaction control block. The readAny flag is
-    set to 0 or 1 by the wrapper functions ubik_BeginTrans() or 
-    ubik_BeginTransReadAny() below.
-
-    We can only begin transaction when we have an up-to-date database.
-*/
-
+/*!
+ * \brief This routine begins a read or write transaction on the transaction
+ * identified by transPtr, in the dbase named by dbase.
+ *
+ * An open mode of ubik_READTRANS identifies this as a read transaction, 
+ * while a mode of ubik_WRITETRANS identifies this as a write transaction.
+ * transPtr is set to the returned transaction control block. 
+ * The readAny flag is set to 0 or 1 by the wrapper functions ubik_BeginTrans() or 
+ * ubik_BeginTransReadAny() below.
+ *
+ * \note We can only begin transaction when we have an up-to-date database.
+ */
 static int
 BeginTrans(register struct ubik_dbase *dbase, afs_int32 transMode,
           struct ubik_trans **transPtr, int readAny)
@@ -503,6 +520,9 @@ BeginTrans(register struct ubik_dbase *dbase, afs_int32 transMode,
     return 0;
 }
 
+/*!
+ * \see BeginTrans()
+ */
 int
 ubik_BeginTrans(register struct ubik_dbase *dbase, afs_int32 transMode,
                struct ubik_trans **transPtr)
@@ -510,6 +530,9 @@ ubik_BeginTrans(register struct ubik_dbase *dbase, afs_int32 transMode,
     return BeginTrans(dbase, transMode, transPtr, 0);
 }
 
+/*!
+ * \see BeginTrans()
+ */
 int
 ubik_BeginTransReadAny(register struct ubik_dbase *dbase, afs_int32 transMode,
                       struct ubik_trans **transPtr)
@@ -517,7 +540,9 @@ ubik_BeginTransReadAny(register struct ubik_dbase *dbase, afs_int32 transMode,
     return BeginTrans(dbase, transMode, transPtr, 1);
 }
 
-/* this routine ends a read or write transaction by aborting it */
+/*!
+ * \brief This routine ends a read or write transaction by aborting it.
+ */
 int
 ubik_AbortTrans(register struct ubik_trans *transPtr)
 {
@@ -559,7 +584,10 @@ ubik_AbortTrans(register struct ubik_trans *transPtr)
     return (code ? code : code2);
 }
 
-/* This routine ends a read or write transaction on the open transaction identified by transPtr.  It returns an error code. */
+/*!
+ * \brief This routine ends a read or write transaction on the open transaction identified by transPtr.
+ * \return an error code.
+ */
 int
 ubik_EndTrans(register struct ubik_trans *transPtr)
 {
@@ -673,8 +701,13 @@ ubik_EndTrans(register struct ubik_trans *transPtr)
     return 0;
 }
 
-/* This routine reads length bytes into buffer from the current position in the database.  The file pointer is updated appropriately (by adding the number of bytes actually transferred), and the length actually transferred is stored in the long integer pointed to by length.  Note that *length is an INOUT parameter: at the start it represents the size of the buffer, and when done, it contains the number of bytes actually transferred.  A short read returns zero for an error code. */
-
+/*!
+ * \brief This routine reads length bytes into buffer from the current position in the database.
+ * 
+ * The file pointer is updated appropriately (by adding the number of bytes actually transferred), and the length actually transferred is stored in the long integer pointed to by length.  A short read returns zero for an error code.
+ *
+ * \note *length is an INOUT parameter: at the start it represents the size of the buffer, and when done, it contains the number of bytes actually transferred.
+ */
 int
 ubik_Read(register struct ubik_trans *transPtr, char *buffer,
          afs_int32 length)
@@ -698,9 +731,11 @@ ubik_Read(register struct ubik_trans *transPtr, char *buffer,
     return code;
 }
 
-/* This routine will flush the io data in the iovec structures. It first
- * flushes to the local disk and then uses ContactQuorum to write it to 
- * the other servers.
+/*!
+ * \brief This routine will flush the io data in the iovec structures. 
+ *
+ * It first flushes to the local disk and then uses ContactQuorum to write it
+ * to the other servers.
  */
 int
 ubik_Flush(struct ubik_trans *transPtr)
@@ -826,8 +861,13 @@ ubik_Write(register struct ubik_trans *transPtr, char *buffer,
     return error;
 }
 
-/* This sets the file pointer associated with the current transaction to the appropriate file and byte position.  Unlike Unix files, a transaction is labelled by both a file number (fileid) and a byte position relative to the specified file (position). */
-
+/*!
+ * \brief This sets the file pointer associated with the current transaction
+ * to the appropriate file and byte position.
+ *
+ * Unlike Unix files, a transaction is labelled by both a file number \p fileid
+ * and a byte position relative to the specified file \p position.
+ */
 int
 ubik_Seek(register struct ubik_trans *transPtr, afs_int32 fileid,
          afs_int32 position)
@@ -846,8 +886,10 @@ ubik_Seek(register struct ubik_trans *transPtr, afs_int32 fileid,
     return code;
 }
 
-/* This call returns the file pointer associated with the specified transaction in fileid and position. */
-
+/*!
+ * \brief This call returns the file pointer associated with the specified
+ * transaction in \p fileid and \p position.
+ */
 int
 ubik_Tell(register struct ubik_trans *transPtr, afs_int32 * fileid,
          afs_int32 * position)
@@ -859,8 +901,10 @@ ubik_Tell(register struct ubik_trans *transPtr, afs_int32 * fileid,
     return 0;
 }
 
-/* This sets the file size for the currently-selected file to length bytes, if length is less than the file's current size. */
-
+/*!
+ * \brief This sets the file size for the currently-selected file to \p length
+ * bytes, if length is less than the file's current size.
+ */
 int
 ubik_Truncate(register struct ubik_trans *transPtr, afs_int32 length)
 {
@@ -897,7 +941,9 @@ ubik_Truncate(register struct ubik_trans *transPtr, afs_int32 length)
     return error;
 }
 
-/* set a lock; all locks are released on transaction end (commit/abort) */
+/*!
+ * \brief set a lock; all locks are released on transaction end (commit/abort)
+ */
 int
 ubik_SetLock(struct ubik_trans *atrans, afs_int32 apos, afs_int32 alen,
             int atype)
@@ -943,7 +989,9 @@ ubik_SetLock(struct ubik_trans *atrans, afs_int32 apos, afs_int32 alen,
     return error;
 }
 
-/* utility to wait for a version # to change */
+/*!
+ * \brief utility to wait for a version # to change
+ */
 int
 ubik_WaitVersion(register struct ubik_dbase *adatabase,
                 register struct ubik_version *aversion)
@@ -962,7 +1010,9 @@ ubik_WaitVersion(register struct ubik_dbase *adatabase,
     }
 }
 
-/* utility to get the version of the dbase a transaction is dealing with */
+/*!
+ * \brief utility to get the version of the dbase a transaction is dealing with
+ */
 int
 ubik_GetVersion(register struct ubik_trans *atrans,
                register struct ubik_version *avers)
@@ -971,11 +1021,14 @@ ubik_GetVersion(register struct ubik_trans *atrans,
     return 0;
 }
 
-/* Facility to simplify database caching.  Returns zero if last trans was done
-   on the local server and was successful.  If return value is non-zero and the
-   caller is a server caching part of the Ubik database, it should invalidate
-   that cache.  A return value of -1 means bad (NULL) argument. */
-
+/*!
+ * \brief Facility to simplify database caching.  
+ * \return zero if last trans was done on the local server and was successful.
+ * \return -1 means bad (NULL) argument.
+ * 
+ * If return value is non-zero and the caller is a server caching part of the 
+ * Ubik database, it should invalidate that cache.
+ */
 int
 ubik_CacheUpdate(register struct ubik_trans *atrans)
 {
@@ -984,6 +1037,14 @@ ubik_CacheUpdate(register struct ubik_trans *atrans)
     return vcmp(atrans->dbase->cachedVersion, atrans->dbase->version) != 0;
 }
 
+/*!
+ * "Who said anything about panicking?" snapped Arthur. 
+ * "This is still just the culture shock. You wait till I've settled down
+ * into the situation and found my bearings. \em Then I'll start panicking!"
+ * --Authur Dent
+ *
+ * \returns There is no return from panic.
+ */
 int
 panic(char *a, char *b, char *c, char *d)
 {
@@ -994,10 +1055,10 @@ panic(char *a, char *b, char *c, char *d)
     exit(1);                   /* never know, though  */
 }
 
-/*
-** This functions takes an IP addresses as its parameter. It returns the
-** the primary IP address that is on the host passed in.
-*/
+/*!
+ * This function takes an IP addresses as its parameter. It returns the
+ * the primary IP address that is on the host passed in, or 0 if not found.
+ */
 afs_uint32
 ubikGetPrimaryInterfaceAddr(afs_uint32 addr)
 {
index 690138f..39ed8d3 100644 (file)
 #include <ubik_int.h>
 #endif /* defined(UKERNEL) */
 
-/* ubik_trans types */
+/*! \name ubik_trans types */
 #define        UBIK_READTRANS      0
 #define        UBIK_WRITETRANS     1
+/*\}*/
 
-/* ubik_lock types */
+/*! \name ubik_lock types */
 #define        LOCKREAD            1
 #define        LOCKWRITE           2
 #if !defined(UBIK_PAUSE)
 #define        LOCKWAIT            3
 #endif /* UBIK_PAUSE */
+/*\}*/
 
-/* ubik client flags */
-#define UPUBIKONLY         1   /* only check servers presumed functional */
+/*! \name ubik client flags */
+#define UPUBIKONLY         1   /*!< only check servers presumed functional */
+/*\}*/
 
-/* RX services types */
+/*! \name RX services types */
 #define        VOTE_SERVICE_ID     50
 #define        DISK_SERVICE_ID     51
-#define        USER_SERVICE_ID     52  /* Since most applications use same port! */
+#define        USER_SERVICE_ID     52  /*!< Since most applications use same port! */
+/*\}*/
 
 #define        UBIK_MAGIC      0x354545
 
-/* global ubik parameters */
-#define        MAXSERVERS          20  /* max number of servers */
+/*! \name global ubik parameters */
+#define        MAXSERVERS          20  /*!< max number of servers */
+/*\}*/
 
-/* version comparison macro */
+/*! version comparison macro */
 #define vcmp(a,b) ((a).epoch == (b).epoch? ((a).counter - (b).counter) : ((a).epoch - (b).epoch))
 
-/* ubik_client state bits */
-#define        CFLastFailed        1   /* last call failed to this guy (to detect down hosts) */
+/*! \name ubik_client state bits */
+#define        CFLastFailed        1   /*!< last call failed to this guy (to detect down hosts) */
+/*\}*/
 
 #ifdef AFS_PTHREAD_ENV
 #include <pthread.h>
 #include <lwp.h>
 #endif
 
-/* per-client structure for ubik */
+/*!
+ * \brief per-client structure for ubik
+ */
 struct ubik_client {
-    short initializationState; /* ubik client init state */
-    short states[MAXSERVERS];  /* state bits */
+    short initializationState; /*!< ubik client init state */
+    short states[MAXSERVERS];  /*!< state bits */
     struct rx_connection *conns[MAXSERVERS];
     afs_int32 syncSite;
 #ifdef AFS_PTHREAD_ENV
@@ -99,35 +107,41 @@ struct ubik_client {
 #define        ubik_GetRPCConn(astr,aindex)    ((aindex) >= MAXSERVERS? 0 : (astr)->conns[aindex])
 #define        ubik_GetRPCHost(astr,aindex)    ((aindex) >= MAXSERVERS? 0 : (astr)->hosts[aindex])
 
-/* ubik header file structure */
+/*!
+ * \brief ubik header file structure
+ */
 struct ubik_hdr {
-    afs_int32 magic;           /* magic number */
-    short pad1;                        /* some 0-initd padding */
-    short size;                        /* header allocation size */
-    struct ubik_version version;       /* the version for this file */
+    afs_int32 magic;           /*!< magic number */
+    short pad1;                        /*!< some 0-initd padding */
+    short size;                        /*!< header allocation size */
+    struct ubik_version version;       /*!< the version for this file */
 };
 
-/* representation of a ubik transaction */
+/*!
+ * \brief representation of a ubik transaction
+ */
 struct ubik_trans {
-    struct ubik_dbase *dbase;  /* corresponding database */
-    struct ubik_trans *next;   /* in the list */
-    afs_int32 locktype;                /* transaction lock */
-    struct ubik_trunc *activeTruncs;   /* queued truncates */
-    struct ubik_tid tid;       /* transaction id of this trans (if write trans.) */
-    afs_int32 minCommitTime;   /* time before which this trans can't commit */
-    afs_int32 seekFile;                /* seek ptr: file number */
-    afs_int32 seekPos;         /* seek ptr: offset therein */
-    short flags;               /* trans flag bits */
-    char type;                 /* type of trans */
+    struct ubik_dbase *dbase;  /*!< corresponding database */
+    struct ubik_trans *next;   /*!< in the list */
+    afs_int32 locktype;                /*!< transaction lock */
+    struct ubik_trunc *activeTruncs;   /*!< queued truncates */
+    struct ubik_tid tid;       /*!< transaction id of this trans (if write trans.) */
+    afs_int32 minCommitTime;   /*!< time before which this trans can't commit */
+    afs_int32 seekFile;                /*!< seek ptr: file number */
+    afs_int32 seekPos;         /*!< seek ptr: offset therein */
+    short flags;               /*!< trans flag bits */
+    char type;                 /*!< type of trans */
     iovec_wrt iovec_info;
     iovec_buf iovec_data;
 };
 
-/* representation of a truncation operation */
+/*!
+ * \brief representation of a truncation operation
+ */
 struct ubik_trunc {
     struct ubik_trunc *next;
-    afs_int32 file;            /* file to truncate */
-    afs_int32 length;          /* new size */
+    afs_int32 file;            /*!< file to truncate */
+    afs_int32 length;          /*!< new size */
 };
 
 struct ubik_stat {
@@ -138,24 +152,27 @@ struct ubik_stat {
 #if defined(UKERNEL)
 #include "afs/lock.h"
 #else /* defined(UKERNEL) */
-#include <lock.h>              /* just to make sure we've go this */
+#include <lock.h>              /* just to make sure we've got this */
 #endif /* defined(UKERNEL) */
 
-/* representation of a ubik database.  Contains info on low-level disk access routines
-    for use by disk transaction module.
-*/
+/*!
+ * \brief representation of a ubik database.
+ *
+ * Contains info on low-level disk access routines 
+ * for use by disk transaction module.
+ */
 struct ubik_dbase {
-    char *pathName;            /* root name for dbase */
-    struct ubik_trans *activeTrans;    /* active transaction list */
-    struct ubik_version version;       /* version number */
+    char *pathName;            /*!< root name for dbase */
+    struct ubik_trans *activeTrans;    /*!< active transaction list */
+    struct ubik_version version;       /*!< version number */
 #if defined(UKERNEL)
-    struct afs_lock versionLock;       /* lock on version number */
+    struct afs_lock versionLock;       /*!< lock on version number */
 #else                          /* defined(UKERNEL) */
-    struct Lock versionLock;   /* lock on version number */
+    struct Lock versionLock;   /*!< lock on version number */
 #endif                         /* defined(UKERNEL) */
-    afs_int32 tidCounter;      /* last RW or RO trans tid counter */
-    afs_int32 writeTidCounter; /* last write trans tid counter */
-    afs_int32 flags;           /* flags */
+    afs_int32 tidCounter;      /*!< last RW or RO trans tid counter */
+    afs_int32 writeTidCounter; /*!< last write trans tid counter */
+    afs_int32 flags;           /*!< flags */
     /* physio procedures */
     int (*read) (struct ubik_dbase * adbase, afs_int32 afile, char *abuffer,
                 afs_int32 apos, afs_int32 alength);
@@ -167,115 +184,131 @@ struct ubik_dbase {
     int (*stat) (struct ubik_dbase * adbase, afs_int32 afid,
                 struct ubik_stat * astat);
     int (*open) (struct ubik_dbase * adbase, afs_int32 afid);
-    int (*setlabel) (struct ubik_dbase * adbase, afs_int32 afile, struct ubik_version * aversion);     /* set the version label */
-    int (*getlabel) (struct ubik_dbase * adbase, afs_int32 afile, struct ubik_version * aversion);     /* retrieve the version label */
-    int (*getnfiles) (struct ubik_dbase * adbase);     /* find out number of files */
-    short readers;             /* number of current read transactions */
-    struct ubik_version cachedVersion; /* version of caller's cached data */
+    int (*setlabel) (struct ubik_dbase * adbase, afs_int32 afile, struct ubik_version * aversion);     /*!< set the version label */
+    int (*getlabel) (struct ubik_dbase * adbase, afs_int32 afile, struct ubik_version * aversion);     /*!< retrieve the version label */
+    int (*getnfiles) (struct ubik_dbase * adbase);     /*!< find out number of files */
+    short readers;             /*!< number of current read transactions */
+    struct ubik_version cachedVersion; /*!< version of caller's cached data */
 #ifdef AFS_PTHREAD_ENV
-    pthread_cond_t version_cond;    /* condition variable to manage changes to version */
-    pthread_cond_t flags_cond;      /* condition variable to manage changes to flags */
+    pthread_cond_t version_cond;    /*!< condition variable to manage changes to version */
+    pthread_cond_t flags_cond;      /*!< condition variable to manage changes to flags */
   pthread_mutex_t version_mutex;
   pthread_mutex_t flags_mutex;
 #endif
 };
 
-/* procedures for automatically authenticating ubik connections */
+/*! \name procedures for automatically authenticating ubik connections */
 extern int (*ubik_CRXSecurityProc) ();
 extern char *ubik_CRXSecurityRock;
 extern int (*ubik_SRXSecurityProc) ();
 extern char *ubik_SRXSecurityRock;
 extern int (*ubik_CheckRXSecurityProc) ();
 extern char *ubik_CheckRXSecurityRock;
+/*\}*/
 
 /****************INTERNALS BELOW ****************/
 
 #ifdef UBIK_INTERNALS
-/* some ubik parameters */
-#define        UBIK_PAGESIZE       1024        /* fits in current r packet */
-#define        UBIK_LOGPAGESIZE    10  /* base 2 log thereof */
-#define        NBUFFERS            20  /* number of 1K buffers */
-#define        HDRSIZE             64  /* bytes of header per dbfile */
-
-/* ubik_dbase flags */
-#define        DBWRITING           1   /* are any write trans. in progress */
+/*! \name some ubik parameters */
+#define        UBIK_PAGESIZE       1024        /*!< fits in current r packet */
+#define        UBIK_LOGPAGESIZE    10  /*!< base 2 log thereof */
+#define        NBUFFERS            20  /*!< number of 1K buffers */
+#define        HDRSIZE             64  /*!< bytes of header per dbfile */
+/*\}*/
+
+/*! \name ubik_dbase flags */
+#define        DBWRITING           1   /*!< are any write trans. in progress */
 #if defined(UBIK_PAUSE)
-#define DBVOTING            2  /* the beacon task is polling */
+#define DBVOTING            2  /*!< the beacon task is polling */
 #endif /* UBIK_PAUSE */
+/*\}*/
 
-/* ubik trans flags */
-#define        TRDONE              1   /* commit or abort done */
-#define        TRABORT             2   /* if TRDONE, tells if aborted */
-#define TRREADANY          4   /* read any data available in trans */
+/*!\name ubik trans flags */
+#define        TRDONE              1   /*!< commit or abort done */
+#define        TRABORT             2   /*!< if #TRDONE, tells if aborted */
+#define TRREADANY          4   /*!< read any data available in trans */
 #if defined(UBIK_PAUSE)
-#define TRSETLOCK           8  /* SetLock is using trans */
-#define TRSTALE             16 /* udisk_end during getLock */
+#define TRSETLOCK           8  /*!< SetLock is using trans */
+#define TRSTALE             16 /*!< udisk_end during getLock */
 #endif /* UBIK_PAUSE */
+/*\}*/
 
-/* ubik_lock flags */
+/*! \name ubik_lock flags */
 #define        LWANT               1
+/*\}*/
 
-/* ubik system database numbers */
+/*! \name ubik system database numbers */
 #define        LOGFILE             (-1)
-
-/* define log opcodes */
-#define        LOGNEW              100 /* start transaction */
-#define        LOGEND              101 /* commit (good) end transaction */
-#define        LOGABORT            102 /* abort (fail) transaction */
-#define        LOGDATA             103 /* data */
-#define        LOGTRUNCATE         104 /* truncate operation */
-
-/* time constant for replication algorithms: the R time period is 20 seconds.  Both SMALLTIME
-    and BIGTIME must be larger than RPCTIMEOUT+max(RPCTIMEOUT,POLLTIME),
-    so that timeouts do not prevent us from getting through to our servers in time.
-
-    We use multi-R to time out multiple down hosts concurrently.
-    The only other restrictions:  BIGTIME > SMALLTIME and
-    BIGTIME-SMALLTIME > MAXSKEW (the clock skew).
-*/
+/*\}*/
+
+/*! \name define log opcodes */
+#define        LOGNEW              100 /*!< start transaction */
+#define        LOGEND              101 /*!< commit (good) end transaction */
+#define        LOGABORT            102 /*!< abort (fail) transaction */
+#define        LOGDATA             103 /*!< data */
+#define        LOGTRUNCATE         104 /*!< truncate operation */
+/*\}*/
+
+/*!
+ * \name timer constants
+ * time constant for replication algorithms: the R time period is 20 seconds.  Both 
+ * #SMALLTIME and #BIGTIME must be larger than #RPCTIMEOUT+max(#RPCTIMEOUT, #POLLTIME),
+ * so that timeouts do not prevent us from getting through to our servers in time.
+ *
+ * We use multi-R to time out multiple down hosts concurrently.
+ * The only other restrictions:  #BIGTIME > #SMALLTIME and
+ * #BIGTIME-#SMALLTIME > #MAXSKEW (the clock skew).
+ */
 #define MAXSKEW        10
 #define POLLTIME 15
 #define RPCTIMEOUT 20
 #define BIGTIME 75
 #define SMALLTIME 60
+/*\}*/
 
-/* the per-server state, used by the sync site to keep track of its charges */
+/*!
+ * \brief the per-server state, used by the sync site to keep track of its charges
+ */
 struct ubik_server {
-    struct ubik_server *next;  /* next ptr */
-    afs_uint32 addr[UBIK_MAX_INTERFACE_ADDR];  /* network order, addr[0] is primary */
-    afs_int32 lastVoteTime;    /* last time yes vote received */
-    afs_int32 lastBeaconSent;  /* last time beacon attempted */
-    struct ubik_version version;       /* version, only used during recovery */
-    struct rx_connection *vote_rxcid;  /* cid to use to contact dude for votes */
-    struct rx_connection *disk_rxcid;  /* cid to use to contact dude for disk reqs */
-    char lastVote;             /* true if last vote was yes */
-    char up;                   /* is it up? */
-    char beaconSinceDown;      /* did beacon get through since last crash? */
-    char currentDB;            /* is dbase up-to-date */
-    char magic;                        /* the one whose vote counts twice */
-    char isClone;              /* is only a clone, doesn't vote */
+    struct ubik_server *next;  /*!< next ptr */
+    afs_uint32 addr[UBIK_MAX_INTERFACE_ADDR];  /*!< network order, addr[0] is primary */
+    afs_int32 lastVoteTime;    /*!< last time yes vote received */
+    afs_int32 lastBeaconSent;  /*!< last time beacon attempted */
+    struct ubik_version version;       /*!< version, only used during recovery */
+    struct rx_connection *vote_rxcid;  /*!< cid to use to contact dude for votes */
+    struct rx_connection *disk_rxcid;  /*!< cid to use to contact dude for disk reqs */
+    char lastVote;             /*!< true if last vote was yes */
+    char up;                   /*!< is it up? */
+    char beaconSinceDown;      /*!< did beacon get through since last crash? */
+    char currentDB;            /*!< is dbase up-to-date */
+    char magic;                        /*!< the one whose vote counts twice */
+    char isClone;              /*!< is only a clone, doesn't vote */
 };
 
-/* hold and release functions on a database */
+/*! \name hold and release functions on a database */
 #define        DBHOLD(a)       ObtainWriteLock(&((a)->versionLock))
 #define        DBRELE(a)       ReleaseWriteLock(&((a)->versionLock))
+/*\}*/
 
 /* globals */
 
-/* list of all servers in the system */
+/*!name list of all servers in the system */
 extern struct ubik_server *ubik_servers;
 extern char amIClone;
+/*\}*/
 
-/* network port info */
+/*! \name network port info */
 extern short ubik_callPortal;
+/*\}*/
 
-/* urecovery state bits for sync site */
+/*! \name urecovery state bits for sync site */
 #define        UBIK_RECSYNCSITE        1       /* am sync site */
 #define        UBIK_RECFOUNDDB         2       /* found acceptable dbase from quorum */
 #define        UBIK_RECHAVEDB          4       /* fetched best dbase */
 #define        UBIK_RECLABELDB         8       /* relabelled dbase */
 #define        UBIK_RECSENTDB          0x10    /* sent best db to *everyone* */
 #define        UBIK_RECSBETTER         UBIK_RECLABELDB /* last state */
+/*\}*/
 
 extern afs_int32 ubik_quorum;  /* min hosts in quorum */
 extern struct ubik_dbase *ubik_dbase;  /* the database handled by this server */
@@ -314,7 +347,7 @@ extern int uphys_sync(register struct ubik_dbase *adbase, afs_int32 afile);
 extern void uphys_invalidate(register struct ubik_dbase *adbase, 
                             afs_int32 afid);
 
-/* recovery.c */
+/*! \name recovery.c */
 extern int urecovery_ResetState(void);
 extern int urecovery_LostServer(void);
 extern int urecovery_AllBetter(register struct ubik_dbase *adbase,
@@ -324,7 +357,7 @@ extern int urecovery_CheckTid(register struct ubik_tid *atid);
 extern int urecovery_Initialize(register struct ubik_dbase *adbase);
 extern void *urecovery_Interact(void *);
 extern int DoProbe(struct ubik_server *server);
-
+/*\}*/
 
 extern void *ubeacon_Interact(void *);
 extern int sdisk_Interact();
@@ -339,18 +372,20 @@ extern int DISK_WriteV();
 extern int DISK_Truncate();
 extern int DISK_SetVersion();
 
-/* disk.c */
+/*! \name disk.c */
 extern int udisk_abort(struct ubik_trans *atrans);
+/*\}*/
 
-/* lock.c */
+/*! \name lock.c */
 extern void ulock_relLock(struct ubik_trans *atrans);
+/*\}*/
 
 #endif /* UBIK_INTERNALS */
 
 extern afs_int32 ubik_nBuffers;
 
-/*
- * Public function prototypes
+/*!
+ * \name Public function prototypes
  */
 
 extern int ubik_ParseClientList(int argc, char **argv, afs_int32 * aothers);
@@ -370,6 +405,7 @@ extern afs_int32 ubik_CallIter(int (*aproc) (), struct ubik_client *aclient,
                               long p13, long p14, long p15, long p16);
 
 extern struct rx_connection *ubik_RefreshConn(struct rx_connection *tc);
+/*\}*/
 
 /* ubik.c */
 extern int ubik_BeginTrans(register struct ubik_dbase *dbase,
index 47e6584..ee9d4aa 100644 (file)
@@ -46,11 +46,11 @@ RCSID
 #endif /* defined(UKERNEL) */
 
 
-short ubik_initializationState;        /* initial state is zero */
+short ubik_initializationState;        /*!< initial state is zero */
 
 
-/*
- * parse list for clients
+/*!
+ * \brief Parse list for clients.
  */
 int
 ubik_ParseClientList(int argc, char **argv, afs_int32 * aothers)
@@ -115,34 +115,34 @@ afs_random_once(void)
 }
 
 #endif
-/* 
- * Random number generator and constants from KnuthV2 2d ed, p170
+
+#if !defined(UKERNEL)
+/*! 
+ * \brief use time and pid to try to get some initial randomness.
+ */
+#define        ranstage(x)     (x)= (afs_uint32) (3141592621U*((afs_uint32)x)+1)
+
+/*! 
+ * \brief Random number generator and constants from KnuthV2 2d ed, p170
  *
- * Rules:
- * X = (aX + c) % m
- * m is a power of two 
- * a % 8 is 5
- * a is 0.73m  should be 0.01m .. 0.99m
- * c is more or less immaterial.  1 or a is suggested.
+ * Rules: \n
+ * X = (aX + c) % m \n
+ * m is a power of two \n
+ * a % 8 is 5 \n
+ * a is 0.73m  should be 0.01m .. 0.99m \n
+ * c is more or less immaterial.  1 or a is suggested. \n
  *
  * NB:  LOW ORDER BITS are not very random.  To get small random numbers,
  *      treat result as <1, with implied binary point, and multiply by 
  *      desired modulus.
+ *
  * NB:  Has to be unsigned, since shifts on signed quantities may preserve
  *      the sign bit.
  * 
  * In this case, m == 2^32, the mod operation is implicit. a == pi, which
  * is used because it has some interesting characteristics (lacks any
  * interesting bit-patterns).   
- * 
  */
-
-/* 
- * use time and pid to try to get some initial randomness.
- */
-#if !defined(UKERNEL)
-#define        ranstage(x)     (x)= (afs_uint32) (3141592621U*((afs_uint32)x)+1)
-
 unsigned int
 afs_random(void)
 {
@@ -171,14 +171,15 @@ afs_random(void)
 
 }
 
-/*
- * returns int 0..14 using the high bits of a pseudo-random number instead of
+/*!
+ * \brief Returns int 0..14 using the high bits of a pseudo-random number instead of
  * the low bits, as the low bits are "less random" than the high ones...
- * slight roundoff error exists, an excercise for the reader.
- * need to multiply by something with lots of ones in it, so multiply by 
+ * 
+ * \todo Slight roundoff error exists, an excercise for the reader.
+ *
+ * Need to multiply by something with lots of ones in it, so multiply by 
  * 8 or 16 is right out.
  */
-
 static unsigned int
 afs_randomMod15(void)
 {
@@ -268,11 +269,12 @@ ubik_ClientInit(register struct rx_connection **serverconns,
     return 0;
 }
 
-/* 
- * ubik_ClientDestroy - destroys a ubik connection.  It calls rx to destroy the
- * component rx connections, then frees the ubik connection structure.
+/*! 
+ * \brief Destroy an ubik connection.
+ *
+ * It calls rx to destroy the component rx connections, then frees the ubik
+ * connection structure.
  */
-
 afs_int32
 ubik_ClientDestroy(struct ubik_client * aclient)
 {
@@ -300,12 +302,11 @@ ubik_ClientDestroy(struct ubik_client * aclient)
     return 0;
 }
 
-/*
- * RefreshConn -- So that intermittent failures that cause connections to die
+/*!
+ * \brief So that intermittent failures that cause connections to die
  *     don't kill whole ubik connection, refresh them when the connection is in
  *     error.
  */
-
 struct rx_connection *
 ubik_RefreshConn(struct rx_connection *tc)
 {
@@ -357,9 +358,10 @@ ubik_client_init_mutex()
 static int *calls_needsync[SYNCCOUNT]; /* proc calls that need the sync site */
 static int synccount = 0;
 
-/*
+/*!
  * call this instead of stub and we'll guarantee to find a host that's up.
- * in the future, we should also put in a protocol to find the sync site
+ * 
+ * \todo In the future, we should also put in a protocol to find the sync site.
  */
 afs_int32
 ubik_Call(aproc, aclient, aflags, p1, p2, p3, p4, p5, p6, p7, p8, p9, p10,
@@ -514,12 +516,13 @@ ubik_Call(aproc, aclient, aflags, p1, p2, p3, p4, p5, p6, p7, p8, p9, p10,
 
 
 
-/*
- * call this after getting back a UNOTSYNC 
- * note that getting a UNOTSYNC error code back does *not* guarantee
+/*!
+ * \brief Call this after getting back a #UNOTSYNC.
+ *
+ * \note Getting a #UNOTSYNC error code back does \b not guarantee
  * that there is a sync site yet elected.  However, if there is a sync
  * site out there somewhere, and you're trying an operation that
- * requires a sync site, ubik will return UNOTSYNC, indicating the
+ * requires a sync site, ubik will return #UNOTSYNC, indicating the
  * operation won't work until you find a sync site
  */
 static int
@@ -570,15 +573,14 @@ try_GetSyncSite(register struct ubik_client *aclient, afs_int32 apos)
     return -1;
 }
 
-/* 
- * Create an internal version of ubik_CallIter that takes an additional
- * parameter - to indicate whether the ubik client handle has already
- * been locked.
- */
-
 #define NEED_LOCK 1
 #define NO_LOCK 0
 
+/*! 
+ * \brief Create an internal version of ubik_CallIter that takes an additional
+ * parameter - to indicate whether the ubik client handle has already
+ * been locked.
+ */
 static afs_int32
 CallIter(aproc, aclient, aflags, apos, p1, p2, p3, p4, p5, p6, p7, p8, p9,
         p10, p11, p12, p13, p14, p15, p16, needlock)
@@ -668,9 +670,10 @@ CallIter(aproc, aclient, aflags, apos, p1, p2, p3, p4, p5, p6, p7, p8, p9,
     return code;
 }
 
-/* 
- * call this instead of stub and we'll guarantee to find a host that's up.
- * in the future, we should also put in a protocol to find the sync site
+/*! 
+ * \brief Call this instead of stub and we'll guarantee to find a host that's up.
+ *
+ * \todo In the future, we should also put in a protocol to find the sync site.
  */
 afs_int32
 ubik_Call_New(aproc, aclient, aflags, p1, p2, p3, p4, p5, p6, p7, p8, p9, p10,
@@ -745,8 +748,8 @@ ubik_Call_New(aproc, aclient, aflags, p1, p2, p3, p4, p5, p6, p7, p8, p9, p10,
     return rcode;
 }
 
-/* 
- * This is part of an iterator.  It doesn't handle finding sync sites
+/*!
+ * \brief This is part of an iterator.  It doesn't handle finding sync sites.
  */
 afs_int32
 ubik_CallIter(int (*aproc) (), struct ubik_client *aclient,
index 06cfca3..6f0c246 100644 (file)
@@ -31,10 +31,10 @@ RCSID
 #define UBIK_INTERNALS
 #include "ubik.h"
 
-/* This file contain useful subroutines for parsing command line args for ubik
- *   applications.
+/*! \file
+ * This file contain useful subroutines for parsing command line args for ubik
+ * applications.
  */
-
 ubik_ParseServerList(argc, argv, ahost, aothers)
      int argc;
      char **argv;
index bde8dce..fd28661 100644 (file)
@@ -40,7 +40,7 @@ RCSID
 #include "ubik.h"
 #include "ubik_int.h"
 
-/* needed by Irix. Include a header to get it, or leave it alone. */
+/*! needed by Irix. Include a header to get it, or leave it alone. */
 extern struct hostent *hostutil_GetHostByName();
 
 static short
index da61e60..1314ad8 100644 (file)
@@ -43,9 +43,9 @@ RCSID
 #include <afs/afsint.h>
 #include <afs/cmd.h>
 
-/*
-  Get the appropriate type of ubik client structure out from the system.
-*/
+/*!
+ * \brief Get the appropriate type of ubik client structure out from the system.
+ */
 afs_int32
 ugen_ClientInit(int noAuthFlag, char *confDir, char *cellName, afs_int32 sauth,
               struct ubik_client **uclientp, int (*secproc) (),
index f58f449..712684f 100644 (file)
@@ -33,9 +33,10 @@ RCSID
 #include "utst_int.h"
 
 
-/* useful globals */
+/*! \name useful globals */
 struct ubik_dbase *dbase;
 afs_int32 sleepTime;
+/*\}*/
 
 SAMPLE_Inc(rxconn)
      struct rx_connection *rxconn;
index d61ef05..8a4050e 100644 (file)
@@ -32,96 +32,103 @@ RCSID
 #include "ubik.h"
 #include "ubik_int.h"
 
-/*
-    General Ubik Goal:
-    The goal is to provide reliable operation among N servers, such that any
-    server can crash with the remaining servers continuing operation within a
-    short period of time.  While a *short* outage is acceptable, this time
-    should be order of 3 minutes or less.
-    
-    Theory of operation:
-    
-    Note: SMALLTIME and BIGTIME are essentially the same time value, separated
-    only by the clock skew, MAXSKEW.  In general, if you are making guarantees
-    for someone else, promise them no more than SMALLTIME seconds of whatever
-    invariant you provide.  If you are waiting to be sure some invariant is now
-    *false*, wait at least BIGTIME seconds to be sure that SMALLTIME seconds
-    has passed at the other site.
-
-    Now, back to the design:
-    One site in the collection is a special site, designated the *sync* site.
-    The sync site sends periodic messages, which can be thought of as
-    keep-alive messages.  When a non-sync site hears from the sync site, it
-    knows that it is getting updates for the next SMALLTIME seconds from that
-    sync site.
-    
-    If a server does not hear from the sync site in SMALLTIME seconds, it
-    determines that it no longer is getting updates, and thus refuses to give
-    out potentially out-of-date data.  If a sync site can not muster a majority
-    of servers to agree that it is the sync site, then there is a possibility
-    that a network partition has occurred, allowing another server to claim to
-    be the sync site.  Thus, any time that the sync site has not heard from a
-    majority of the servers in the last SMALLTIME seconds, it voluntarily
-    relinquishes its role as sync site.
-    
-    While attempting to nominate a new sync site, certain rules apply.  First,
-    a server can not reply "ok" (return 1 from ServBeacon) to two different
-    hosts in less than BIGTIME seconds; this allows a server that has heard
-    affirmative replies from a majority of the servers to know that no other
-    server in the network has heard enough affirmative replies in the last
-    BIGTIME seconds to become sync site, too.  The variables ubik_lastYesTime
-    and lastYesHost are used by all servers to keep track of which host they
-    have last replied affirmatively to, when queried by a potential new sync
-    site.
-    
-    Once a sync site has become a sync site, it periodically sends beacon
-    messages with a parameter of 1, indicating that it already has determined
-    it is supposed to be the sync site.  The servers treat such a message as a
-    guarantee that no other site will become sync site for the next SMALLTIME
-    seconds.  In the interim, these servers can answer a query concerning which
-    site is the sync site without any communication with any server.  The
-    variables lastBeaconArrival and lastBeaconHost are used by all servers to
-    keep track of which sync site has last contacted them.
-    
-    One complication occurs while nominating a new sync site: each site may be
-    trying to nominate a different site (based on the value of lastYesHost),
-    yet we must nominate the smallest host (under some order), to prevent this
-    process from looping.  The process could loop by having each server give
-    one vote to another server, but with no server getting a majority of the
-    votes.  To avoid this, we try to withhold our votes for the server with the
-    lowest internet address (an easy-to-generate order).  To this effect, we
-    keep track (in lowestTime and lowestHost) of the lowest server trying to
-    become a sync site.  We wait for this server unless there is already a sync
-    site (indicated by ServBeacon's parameter being 1).
-*/
-
-afs_int32 ubik_debugFlag = 0;  /* print out debugging messages? */
-
-/* these statics are used by all sites in nominating new sync sites */
-afs_int32 ubik_lastYesTime = 0;        /* time we sent the last *yes* vote */
-static afs_uint32 lastYesHost = 0xffffffff;    /* host to which we sent *yes* vote */
-/* Next is time sync site began this vote: guarantees sync site until this + SMALLTIME */
+/*! \file
+ * General Ubik Goal:
+ * The goal is to provide reliable operation among N servers, such that any
+ * server can crash with the remaining servers continuing operation within a
+ * short period of time.  While a \b short outage is acceptable, this time
+ * should be order of 3 minutes or less.
+ *
+ * Theory of operation:
+ *
+ * Note: #SMALLTIME and #BIGTIME are essentially the same time value, separated
+ * only by the clock skew, #MAXSKEW.  In general, if you are making guarantees
+ * for someone else, promise them no more than #SMALLTIME seconds of whatever
+ * invariant you provide.  If you are waiting to be sure some invariant is now
+ * \b false, wait at least #BIGTIME seconds to be sure that #SMALLTIME seconds
+ * has passed at the other site.
+ *
+ * Now, back to the design:
+ * One site in the collection is a special site, designated the \b sync site.
+ * The sync site sends periodic messages, which can be thought of as
+ * keep-alive messages.  When a non-sync site hears from the sync site, it
+ * knows that it is getting updates for the next #SMALLTIME seconds from that
+ * sync site.
+ *
+ * If a server does not hear from the sync site in #SMALLTIME seconds, it
+ * determines that it no longer is getting updates, and thus refuses to give
+ * out potentially out-of-date data.  If a sync site can not muster a majority
+ * of servers to agree that it is the sync site, then there is a possibility
+ * that a network partition has occurred, allowing another server to claim to
+ * be the sync site.  Thus, any time that the sync site has not heard from a
+ * majority of the servers in the last #SMALLTIME seconds, it voluntarily
+ * relinquishes its role as sync site.
+ * 
+ * While attempting to nominate a new sync site, certain rules apply.  First,
+ * a server can not reply "ok" (return 1 from ServBeacon) to two different
+ * hosts in less than #BIGTIME seconds; this allows a server that has heard
+ * affirmative replies from a majority of the servers to know that no other
+ * server in the network has heard enough affirmative replies in the last
+ * #BIGTIME seconds to become sync site, too.  The variables #ubik_lastYesTime
+ * and #lastYesHost are used by all servers to keep track of which host they
+ * have last replied affirmatively to, when queried by a potential new sync
+ * site.
+ *
+ * Once a sync site has become a sync site, it periodically sends beacon
+ * messages with a parameter of 1, indicating that it already has determined
+ * it is supposed to be the sync site.  The servers treat such a message as a
+ * guarantee that no other site will become sync site for the next #SMALLTIME
+ * seconds.  In the interim, these servers can answer a query concerning which
+ * site is the sync site without any communication with any server.  The
+ * variables #lastBeaconArrival and #lastBeaconHost are used by all servers to
+ * keep track of which sync site has last contacted them.
+ *
+ * One complication occurs while nominating a new sync site: each site may be
+ * trying to nominate a different site (based on the value of #lastYesHost),
+ * yet we must nominate the smallest host (under some order), to prevent this
+ * process from looping.  The process could loop by having each server give
+ * one vote to another server, but with no server getting a majority of the
+ * votes.  To avoid this, we try to withhold our votes for the server with the
+ * lowest internet address (an easy-to-generate order).  To this effect, we
+ * keep track (in #lowestTime and #lowestHost) of the lowest server trying to
+ * become a sync site.  We wait for this server unless there is already a sync
+ * site (indicated by ServBeacon's parameter being 1).
+ */
+
+afs_int32 ubik_debugFlag = 0;  /*!< print out debugging messages? */
+
+/*! \name these statics are used by all sites in nominating new sync sites */
+afs_int32 ubik_lastYesTime = 0;        /*!< time we sent the last \b yes vote */
+static afs_uint32 lastYesHost = 0xffffffff;    /*!< host to which we sent \b yes vote */
+/*\}*/
+/*! \name Next is time sync site began this vote: guarantees sync site until this + SMALLTIME */
 static afs_int32 lastYesClaim = 0;
-static int lastYesState = 0;   /* did last site we voted for claim to be sync site? */
+static int lastYesState = 0;   /*!< did last site we voted for claim to be sync site? */
+/*\}*/
 
-/* used to guarantee that nomination process doesn't loop */
+/*! \name used to guarantee that nomination process doesn't loop */
 static afs_int32 lowestTime = 0;
 static afs_uint32 lowestHost = 0xffffffff;
 static afs_int32 syncTime = 0;
 static afs_int32 syncHost = 0;
+/*\}*/
 
-/* used to remember which dbase version is the one at the sync site (for non-sync sites */
-struct ubik_version ubik_dbVersion;    /* sync site's dbase version */
-struct ubik_tid ubik_dbTid;    /* sync site's tid, or 0 if none */
+/*! \name used to remember which dbase version is the one at the sync site (for non-sync sites) */
+struct ubik_version ubik_dbVersion;    /*!< sync site's dbase version */
+struct ubik_tid ubik_dbTid;    /*!< sync site's tid, or 0 if none */
+/*\}*/
 
-/* decide if we should try to become sync site.  The basic rule is that we
+/*!
+ * \brief Decide if we should try to become sync site.
+ *
+ * The basic rule is that we
  * don't run if there is a valid sync site and it ain't us (we have to run if
  * it is us, in order to keep our votes).  If there is no sync site, then we
  * want to run if we're the lowest numbered host running, otherwise we defer to
  * the lowest host.  However, if the lowest host hasn't been heard from for a
  * while, then we start running again, in case he crashed.
  *
- * This function returns true if we should run, and false otherwise.
+ * \return true if we should run, and false otherwise.
  */
 int
 uvote_ShouldIRun(void)
@@ -139,17 +146,20 @@ uvote_ShouldIRun(void)
     return 1;
 }
 
-/* Return the current synchronization site, if any.  Simple approach: if the
+/*!
+ * \brief Return the current synchronization site, if any.
+ *
+ * Simple approach: if the
  * last guy we voted yes for claims to be the sync site, then we we're happy to
  * use that guy for a sync site until the time his mandate expires.  If the guy
  * does not claim to be sync site, then, of course, there's none.
  *
- * In addition, if we lost the sync, we set urecovery_syncSite to an invalid
+ * In addition, if we lost the sync, we set #urecovery_syncSite to an invalid
  * value, indicating that we no longer know which version of the dbase is the
  * one we should have.  We'll get a new one when we next hear from the sync
  * site.
  *
- * This function returns 0 or currently valid sync site.  It can return our own
+ * \return 0 or currently valid sync site.  It can return our own
  * address, if we're the sync site.
  */
 afs_int32
@@ -170,8 +180,11 @@ uvote_GetSyncSite(void)
     return code;
 }
 
-/* called by the sync site to handle vote beacons; if aconn is null, this is a
- * local call; returns 0 or time whe the vote was sent.  It returns 0 if we are
+/*!
+ * \brief called by the sync site to handle vote beacons; if aconn is null, this is a
+ * local call
+ *
+ * \returns 0 or time when the vote was sent.  It returns 0 if we are
  * not voting for this sync site, or the time we actually voted yes, if
  * non-zero.
  */
@@ -333,8 +346,11 @@ SVOTE_Beacon(register struct rx_call * rxcall, afs_int32 astate,
     return vote;
 }
 
-/* handle per-server debug command, where 0 is the first server.  Basic network
-   debugging hooks. */
+/*!
+ * \brief Handle per-server debug command, where 0 is the first server.
+ *
+ * Basic network debugging hooks.
+ */
 afs_int32
 SVOTE_SDebug(struct rx_call * rxcall, afs_int32 awhich,
             register struct ubik_sdebug * aparm)
@@ -382,7 +398,9 @@ SVOTE_XDebug(struct rx_call * rxcall, register struct ubik_debug * aparm,
     return code;
 }
 
-/* handle basic network debug command.  This is the global state dumper */
+/*!
+ * \brief Handle basic network debug command.  This is the global state dumper.
+ */
 afs_int32
 SVOTE_Debug(struct rx_call * rxcall, register struct ubik_debug * aparm)
 {
@@ -466,7 +484,9 @@ SVOTE_SDebugOld(struct rx_call * rxcall, afs_int32 awhich,
 }
 
 
-/* handle basic network debug command.  This is the global state dumper */
+/*!
+ * \brief Handle basic network debug command.  This is the global state dumper.
+ */
 afs_int32
 SVOTE_DebugOld(struct rx_call * rxcall,
               register struct ubik_debug_old * aparm)
@@ -523,7 +543,9 @@ SVOTE_DebugOld(struct rx_call * rxcall,
 }
 
 
-/* get the sync site; called by remote servers to find where they should go */
+/*!
+ * \brief Get the sync site; called by remote servers to find where they should go.
+ */
 afs_int32
 SVOTE_GetSyncSite(register struct rx_call * rxcall,
                  register afs_int32 * ahost)
@@ -551,7 +573,9 @@ ubik_print(char *a, char *b, char *c, char *d, char *e, char *f, char *g,
     return 0;
 }
 
-/* called once/run to init the vote module */
+/*!
+ * \brief Called once/run to init the vote module
+ */
 int
 uvote_Init(void)
 {