Documentation update.

libdfa/smash.h

@@ -42,7 +42,7 @@ terms specified in this license.
 
 #include <pbl/pbl.h>
 //#include <pbl/jbhash.h>
-#include <lladd/operations/linearHash.h>
+#include <lladd/operations.h>
 #include <libdfa/statemachine.h>
 /** State machine hash library. */
 

lladd.pws

@@ -11,7 +11,7 @@ filter.file.ignore.hidden=0
 filter.dir.ignore.hidden=0
 
 [filenumbers]
-0=1
+0=22
 1=1
 2=12
 3=2
@@ -78,8 +78,6 @@ filter.dir.ignore.hidden=0
 3=0:9
 4=0:10
 5=0:11
-6=0:11:4
-7=0:11:5
 
 [executer args]
 0=check_linearHash

lladd/operations/alloc.h

@@ -1,16 +1,20 @@
-#include <lladd/operations.h>
-
-#ifndef __ALLOC_H
-#define __ALLOC_H
-
 /**
    @file 
 
+   Allocates and deallocates records.
+
+   @todo Talloc() should reuse space freed by Tdealloc(), but
+   currently just leaks it.
+
    @ingroup OPERATIONS
 
    $Id$
 */
 
+
+#ifndef __ALLOC_H
+#define __ALLOC_H 1
+
 Operation getAlloc();
 Operation getDealloc();
 Operation getRealloc();
@@ -21,12 +25,26 @@ Operation getRealloc();
     @param The transaction responsible for the allocation @param The
     size of the new record to be allocated.  (Talloc may allocate a
     blob if the record will not easily fit on a page.)
+
+    @return the recordid of the new record.
 */
 recordid Talloc(int xid, long size);
 
-/** @todo Currently, we just leak store space on dealloc. */
+/** 
+   Free a record.  
+    @todo Currently, we just leak store space on dealloc. 
+*/
 void Tdealloc(int xid, recordid rid);
 
+/**
+   Return the type of a record, as returned by getRecordType.
+    
+    @todo document TrecordType
+    @see getRecordType
+
+*/
 int TrecordType(int xid, recordid rid);
 
 #endif
+
+

lladd/operations/arrayList.h

@@ -1,16 +1,58 @@
-#include <lladd/operations.h>
+/*---
+This software is copyrighted by the Regents of the University of
+California, and other parties. The following terms apply to all files
+associated with the software unless explicitly disclaimed in
+individual files.
 
-#ifndef __ARRAY_LIST_H
+The authors hereby grant permission to use, copy, modify, distribute,
-#define __ARRAY_LIST_H
+and license this software and its documentation for any purpose,
+provided that existing copyright notices are retained in all copies
+and that this notice is included verbatim in any distributions. No
+written agreement, license, or royalty fee is required for any of the
+authorized uses. Modifications to this software may be copyrighted by
+their authors and need not follow the licensing terms described here,
+provided that the new terms are clearly indicated on the first page of
+each file where they apply.
 
+IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY
+FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
+ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY
+DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.
+
+THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES,
+INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
+NON-INFRINGEMENT. THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, AND
+THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE
+MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
+
+GOVERNMENT USE: If you are acquiring this software on behalf of the
+U.S. government, the Government shall have only "Restricted Rights" in
+the software and related documentation as defined in the Federal
+Acquisition Regulations (FARs) in Clause 52.227.19 (c) (2). If you are
+acquiring the software on behalf of the Department of Defense, the
+software shall be classified as "Commercial Computer Software" and the
+Government shall have only "Restricted Rights" as defined in Clause
+252.227-7013 (c) (1) of DFARs. Notwithstanding the foregoing, the
+authors grant the U.S. Government and others acting in its behalf
+permission to use and distribute the software in accordance with the
+terms specified in this license.
+---*/
 /**
    @file 
 
+   Implements an extendible array of fixed length records with O(1) 
+   complexity for all operations.
+
    @ingroup OPERATIONS
 
    $Id$
 */
 
+#ifndef __ARRAY_LIST_H
+#define __ARRAY_LIST_H
+
 recordid TarrayListAlloc(int xid, int count, int multiplier, int size);
 
 Operation getArrayListAlloc();

lladd/operations/decrement.h

@@ -42,7 +42,8 @@ terms specified in this license.
 /**
  * @file
  *
- * function definitions for decrement
+ * sample logical operation that decrements a the contents of a record
+ * by one.  The record should contain a 32-bit integer.
  *
  * @ingroup OPERATIONS
  * 
@@ -54,8 +55,6 @@ terms specified in this license.
 #ifndef __DECREMENT_H__
 #define __DECREMENT_H__
 
-#include <lladd/operations.h>
-
 #define Tdecrement(xid,rid) Tupdate(xid,rid,0, OPERATION_DECREMENT)
 
 Operation getDecrement();

lladd/operations/increment.h

@@ -42,7 +42,9 @@ terms specified in this license.
 
 /**
  * @file 
- * function definitions for increment
+ *
+ * sample logical operation that increments the contents of a record
+ * by one.  The record should contain a 32-bit integer.
  *
  * Increment provides an example of a logical operation that does not
  * require any extra logging information, and (could someday) support
@@ -59,8 +61,6 @@ terms specified in this license.
 #ifndef __INCREMENT_H__
 #define __INCREMENT_H__
 
-#include <lladd/operations.h>
-
 #define Tincrement(xid,rid) Tupdate(xid,rid,0, OPERATION_INCREMENT)
 
 Operation getIncrement();

lladd/operations/instantSet.h

@@ -42,7 +42,9 @@ terms specified in this license.
 /**
  * @file
  *
- * function definitions for set
+ * sets the contents of the record without producing an undo log
+ * entry; effectively, the set operation 'commits' instantly.
+ * However, the log is not flushed to disk by this operation.
  *
  * @ingroup OPERATIONS
  *
@@ -53,8 +55,6 @@ terms specified in this license.
 #ifndef __INSTANT_SET_H__
 #define __INSTANT_SET_H__
 
-#include <lladd/operations.h>
-
 #define TinstantSet(xid,rid,dat) Tupdate(xid,rid,dat, OPERATION_INSTANT_SET)
 
 Operation getInstantSet();

lladd/operations/linearHash.h

@@ -1,16 +1,21 @@
-#include <lladd/operations.h>
-
-#ifndef __LINEAR_HASH_H
-#define __LINEAR_HASH_H
 
 /**
    @file 
 
+   Experimental (unreliable) hashtable implementation.
+
+   Instead of using Nested top actions, this hashtable implementation
+   uses carefully ordered redo-operations, and simple recovery code.
+   This reduces the amount of information written to the log, but
+   provides concurrency comparable to that provided by linearHashNTA.
+
    @ingroup OPERATIONS
 
    $Id$
 */
 
+#ifndef __LINEAR_HASH_H
+#define __LINEAR_HASH_H
 
 
 recordid ThashInstantAlloc(int xid, int keySize, int valSize) ;

lladd/operations/linearHashNTA.h

@@ -1,3 +1,25 @@
+/** 
+    @file
+
+    A reliable hashtable implementation.  The implementation makes
+    use of nested top actions, and is reentrant.  Currently, all keys
+    and values must be of the same length, although this restriction
+    will eventually be removed.
+
+    The implementation uses a linear hash function, allowing the
+    bucket list to be resized dynamically.  Because the bucket list is
+    built on top of arrayList, all operations are O(1), assuming the
+    hash function behaves correctly.  Currently, linkedListNTA
+    implements the bucket lists.
+
+    @see nestedTopAction.h, linkedListNTA.h, arrayList.h
+
+    @ingroup OPERATIONS
+
+    $id$
+
+*/
+
 #ifndef __LINEAR_HASH_NTA_H
 #define __LINEAR_HASH_NTA_H
 
@@ -10,8 +32,6 @@ typedef struct {
   lladd_linkedList_iterator * it;
 } lladd_hash_iterator;
 
-/** Implementation of a linear hash table that makes use of nested top actions. */
-
 recordid ThashCreate(int xid, int keySize, int valSize);
 void ThashDelete(int xid, recordid hash);
 /* @return 1 if the key was defined, 0 otherwise. */

lladd/operations/linkedListNTA.h

@@ -1,3 +1,17 @@
+/**
+   @file 
+
+   Implements a linked list using nested top actions.  Linked list
+   entries are key, value pairs, where the keys and values are of
+   fixed length.
+
+   @see nestedTopAction.h
+
+   @ingroup OPERATIONS
+
+   $id$
+*/
+
 #ifndef __LINKED_LIST_NTA_H
 #define __LINKED_LIST_NTA_H
 typedef struct {

lladd/operations/lladdhash.h

@@ -10,6 +10,11 @@
 /**
    @file
 
+   Do not use this hashtable.  Instead, use the one provided by
+   linearHashNTA.h
+
+   @deprecated This hash implementation is fundamentally flawed.
+
    A persistant hash, based on logical operations.
 
    lladdhash:  /yad-hash/ n.  LLADD's hash table, based on logical operations.
@@ -26,8 +31,6 @@
 
 */
 
-#include <lladd/operations.h>
-
 #ifndef __LLADDHASH_H__
 #define __LLADDHASH_H__
 

lladd/operations/naiveLinearHash.h

@@ -1,16 +1,19 @@
-#include <lladd/operations.h>
-
-#ifndef __NAIVE_LINEAR_HASH_H
-#define __NAIVE_LINEAR_HASH_H
-
 /**
    @file 
 
+   A non-reentrant, experimental hashtable implementation.  This hash
+   implementation provides the base of linearHash.h, and probably
+   is only of interest to LLADD's developers.
+
    @ingroup OPERATIONS
 
    $Id$
 */
 
+#ifndef __NAIVE_LINEAR_HASH_H
+#define __NAIVE_LINEAR_HASH_H
+
+
 
 recordid ThashAlloc(int xid, int keySize, int valSize) ;
 

lladd/operations/nestedTopActions.h

@@ -42,13 +42,10 @@ terms specified in this license.
 
 /**
  * @file 
- * function definitions for increment
  * 
- * Increment provides an example of a logical operation that does not
+ * Nested top actions provide atomic updates to multiple pages within
- * require any extra logging information, and (could someday) support
+ * a single transaction.  LLADD's nested top actions may be nested
- * reordering.
+ * within each other.
- *
- * @see decrement.h
  *
  * @ingroup OPERATIONS
  *
@@ -59,7 +56,6 @@ terms specified in this license.
 #ifndef __NESTED_TOP_ACTIONS_H__
 #define __NESTED_TOP_ACTIONS_H__
 
-#include <lladd/operations.h>
 void initNestedTopActions();
 void * TbeginNestedTopAction(int xid, int op, const byte* log_arguments, int log_arguments_length);
 lsn_t TendNestedTopAction(int xid, void * handle);

lladd/operations/noop.h

@@ -42,7 +42,8 @@ terms specified in this license.
 /**
  * @file
  *
- * function definitions for set
+ * A logical operation that does nothing.  Mainly useful when
+ * undo-only or redo-only log entries should be generated.
  *
  * @ingroup OPERATIONS
  *
@@ -53,8 +54,6 @@ terms specified in this license.
 #ifndef __NOOP_H__
 #define __NOOP_H__
 
-#include <lladd/operations.h>
-
 Operation getNoop();
 
 #endif

lladd/operations/pageOperations.h

@@ -42,16 +42,17 @@ terms specified in this license.
 
 /**
  * @file 
- * function definitions for increment
  *
- * Increment provides an example of a logical operation that does not
+ * Provides raw access to entire pages.
- * require any extra logging information, and (could someday) support
- * reordering.
  *
- * @see decrement.h
+ * LLADD's pages are PAGE_SIZE bytes long.  Currently, two integers are 
+ * reserved for the LSN and the page type. providing PAGE_SIZE-8 bytes 
+ * of usable space.
  *
  * @ingroup OPERATIONS
  *
+ * @see page.h
+ *
  * $Id$
  */ 
 
@@ -59,8 +60,6 @@ terms specified in this license.
 #ifndef __PAGE_OPERATIONS_H__
 #define __PAGE_OPERATIONS_H__
 
-#include <lladd/operations.h>
-
 /** If defined, then pageOperations.h will reuse freed pages.
     Unfortunately, the current support is not safe for programs with
     multiple concurrent transactions. */

lladd/operations/prepare.h

@@ -41,7 +41,10 @@ terms specified in this license.
 ---*/
 /**
  * @file 
- * Prepare pseudo-operation
+ *
+ * Prepare a transaction to commit so that it will persist
+ * across system crashes.  After recovery, the transaction will be in 
+ * the same state it was in when Tprepare() was called.
  *
  * Tprepare() uses the operation interface to abstract away log handling.
  * It would be nice if the logger API could be simplified by having
@@ -74,8 +77,7 @@ terms specified in this license.
 #ifndef __PREPARE_H__
 #define __PREPARE_H__
 
-#include <lladd/operations.h>
+//#include <lladd/logger/logEntry.h>
-#include <lladd/logger/logEntry.h>
 
 extern recordid prepare_bogus_rec;
 /** 
@@ -88,7 +90,7 @@ extern recordid prepare_bogus_rec;
 
     @param xid Transaction id.
     @param rec must be a valid record id.  any valid recordid will do.  This parameter will be removed eventually.
-    @param dat unused.
+
 */
 #define Tprepare(xid, rec) Tupdate(xid, rec, 0, OPERATION_PREPARE)
 

lladd/operations/set.h

@@ -42,7 +42,8 @@ terms specified in this license.
 /**
  * @file
  *
- * function definitions for set
+ * Methods that change the contents of a record.  An entire record can
+ * be updated at once, or portions of the record can be updated.
  *
  * @ingroup OPERATIONS
  *
@@ -53,8 +54,12 @@ terms specified in this license.
 #ifndef __SET_H__
 #define __SET_H__
 
-#include <lladd/operations.h>
+/**
-
+    Changes the value of a record.
+    @param xid the transaction id
+    @param rid the recordid of the record to be changed.
+    @param dat the new value of the record.
+*/ 
 #define Tset(xid,rid,dat) Tupdate(xid,rid,dat, OPERATION_SET)
 
 Operation getSet();
@@ -62,8 +67,12 @@ Operation getSet();
 Operation getSetRangeInverse();
 Operation getSetRange();
 /**
-  @todo TsetRange is slow as implemented; although it is efficient with log 
+
-  space, it performs a number of extra memcpy() calls over the entire record.
+  Change an interval of bytes within a record.
+
+  @todo TsetRange could be faster.  Although it uses log space
+  efficiently, it performs a number of extra memcpy() calls over the
+  entire record.
 */
 void TsetRange(int xid, recordid rid, int offset, int length, const void * dat);
 

src/lladd/operations/alloc.c

@@ -1,7 +1,7 @@
 #include <config.h>
 #include <lladd/common.h>
 
-#include <lladd/operations/alloc.h>
+#include <lladd/operations.h>
 #include <lladd/transactional.h>
 #include <lladd/bufferManager.h>
 #include "../blobManager.h"

src/lladd/operations/decrement.c

@@ -45,8 +45,7 @@ terms specified in this license.
  * Decrements the given reference by one
  *********************************************/
 
-#include <lladd/operations/decrement.h>
+#include <lladd/operations.h>
-/*#include <lladd/bufferManager.h>*/
 #include "../page.h"
 
 static int operate(int xid, Page * p, lsn_t lsn, recordid r, const void *d) {

src/lladd/operations/increment.c

@@ -45,8 +45,7 @@ terms specified in this license.
  * Increments the given reference by one
  **********************************************/
 
-#include <lladd/operations/increment.h>
+#include <lladd/operations.h>
-/*#include <lladd/bufferManager.h>*/
 #include "../page.h"
 
 static int operate(int xid, Page * p, lsn_t lsn, recordid r, const void *d) {

src/lladd/operations/instantSet.c

@@ -45,8 +45,7 @@ terms specified in this license.
  * sets the given reference to dat
  **********************************************/
 
-#include <lladd/operations/instantSet.h>
+#include <lladd/operations.h>
-#include <lladd/operations/set.h>
 #include "../page.h"
 #include "../page/fixed.h"
 

src/lladd/operations/linearHash.c

@@ -1,5 +1,5 @@
 
-#include <lladd/operations/linearHash.h>
+#include <lladd/operations.h>
 #include <lladd/hash.h>
 #include <limits.h>
 #include <assert.h>

src/lladd/operations/lladdhash.c

@@ -1,8 +1,7 @@
 #include <config.h>
 #include <lladd/common.h>
 
-#include <lladd/operations/lladdhash.h>
+#include <lladd/operations.h>
-#include <lladd/operations/pageOperations.h>
 #include <lladd/bufferManager.h>
 #include <lladd/transactional.h>
 

src/lladd/operations/naiveLinearHash.c

@@ -1,4 +1,4 @@
-#include <lladd/operations/linearHash.h>
+#include <lladd/operations.h>
 #include <lladd/hash.h>
 #include <limits.h>
 #include <assert.h>

src/lladd/operations/noop.c

@@ -45,7 +45,7 @@ terms specified in this license.
  * sets the given reference to dat
  **********************************************/
 
-#include <lladd/operations/noop.h>
+#include <lladd/operations.h>
 #include "../page.h"
 
 static int operate(int xid, Page *p,  lsn_t lsn, recordid rid, const void *dat) {

src/lladd/operations/prepare.c

@@ -46,7 +46,7 @@ terms specified in this license.
  * sets the given reference to dat
  **********************************************/
 
-#include <lladd/operations/prepare.h>
+#include <lladd/operations.h>
 #include "../logger/logWriter.h"
 #include <malloc.h>
 #include <assert.h>

src/lladd/operations/set.c

@@ -45,8 +45,7 @@ terms specified in this license.
  * sets the given reference to dat
  **********************************************/
 
-#include <lladd/operations/set.h>
+#include <lladd/operations.h>
-/*#include <lladd/bufferManager.h>*/
 #include "../page.h"
 #include <string.h>
 #include <assert.h>

src/lladd/page.c

@@ -304,7 +304,7 @@ void readRecordUnlocked(int xid, Page * p, recordid rid, void *buf) {
   }
   assert(rid.page == p->id); 
 }
-/** @TODO getRecordType is a hack.  Instead, each record type should
+/** @todo getRecordType is a hack.  Instead, each record type should
     implement code that decides whether a record exists, and returns its size
     or -1.  Then, getRecordType coudl call that function directly depending on 
 	  page type, etc.

src/lladd/page.h

@@ -254,19 +254,36 @@ lsn_t pageReadLSN(const Page * page);
  * lsn of a page must always increase.  Undos are handled by passing
  * in the LSN of the CLR that records the undo.)
  *
- * @param rid recordid where you want to write @param dat data you
+ * @param page a pointer to an in-memory copy of the page as it
- * wish to write
+ * currently exists.  This copy will be updated by writeRecord.
+ *
+ * @param rid recordid where you want to write 
+ *
+ * @param dat the new value of the record.
+ *
  */
 void writeRecord(int xid, Page * page, lsn_t lsn, recordid rid, const void *dat); 
+/**
+ *  The same as writeRecord, but does not obtain a latch on the page.
+ */
 void writeRecordUnlocked(int xid, Page * page, lsn_t lsn, recordid rid, const void *dat); 
 /**
  * @param xid transaction ID
+ * @param rid the record to be written
  * @param dat buffer for data
  */
 void readRecord(int xid, Page * page, recordid rid, void *dat);
+/**
+ *  The same as readRecord, but does not obtain a latch.
+ */
 void readRecordUnlocked(int xid, Page * p, recordid rid, void *buf);
-
+/**
+   Should be called when transaction xid commits.
+*/
 void pageCommit(int xid);
+/**
+   Should be called when transaction xid aborts.
+*/
 void pageAbort(int xid);
 
 Page* pageMalloc();
@@ -279,8 +296,13 @@ void  pageRealloc(Page * p, int id);
     offset of the page in the file, divided by the page size.
 */
 /*int pageAlloc() ;*/
-
+/**
+   obtains the type of the record pointed to by rid.  
+*/
 int getRecordType(int xid, Page * p, recordid rid);
+/**
+   same as getRecordType(), but does not obtain a lock.
+*/
 int getRecordTypeUnlocked(int xid, Page * p, recordid rid);
 
 END_C_DECLS