From b04e71360f292a4115dd5aa78321d020b2d21358 Mon Sep 17 00:00:00 2001 From: Sears Russell Date: Thu, 20 Jan 2005 21:19:47 +0000 Subject: [PATCH] Documentation update. --- libdfa/smash.h | 2 +- lladd.pws | 4 +-- lladd/operations/alloc.h | 30 ++++++++++++---- lladd/operations/arrayList.h | 48 ++++++++++++++++++++++++-- lladd/operations/decrement.h | 5 ++- lladd/operations/increment.h | 6 ++-- lladd/operations/instantSet.h | 6 ++-- lladd/operations/linearHash.h | 13 ++++--- lladd/operations/linearHashNTA.h | 24 +++++++++++-- lladd/operations/linkedListNTA.h | 14 ++++++++ lladd/operations/lladdhash.h | 7 ++-- lladd/operations/naiveLinearHash.h | 13 ++++--- lladd/operations/nestedTopActions.h | 12 +++---- lladd/operations/noop.h | 5 ++- lladd/operations/pageOperations.h | 13 ++++--- lladd/operations/prepare.h | 12 ++++--- lladd/operations/set.h | 19 +++++++--- src/lladd/operations/alloc.c | 2 +- src/lladd/operations/decrement.c | 3 +- src/lladd/operations/increment.c | 3 +- src/lladd/operations/instantSet.c | 3 +- src/lladd/operations/linearHash.c | 2 +- src/lladd/operations/lladdhash.c | 3 +- src/lladd/operations/naiveLinearHash.c | 2 +- src/lladd/operations/noop.c | 2 +- src/lladd/operations/prepare.c | 2 +- src/lladd/operations/set.c | 3 +- src/lladd/page.c | 2 +- src/lladd/page.h | 30 +++++++++++++--- 29 files changed, 207 insertions(+), 83 deletions(-) diff --git a/libdfa/smash.h b/libdfa/smash.h index 5a86864..9af893f 100644 --- a/libdfa/smash.h +++ b/libdfa/smash.h @@ -42,7 +42,7 @@ terms specified in this license. #include //#include -#include +#include #include /** State machine hash library. */ diff --git a/lladd.pws b/lladd.pws index f9c084c..acb7acb 100644 --- a/lladd.pws +++ b/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 diff --git a/lladd/operations/alloc.h b/lladd/operations/alloc.h index ab0d200..20f3bf0 100644 --- a/lladd/operations/alloc.h +++ b/lladd/operations/alloc.h @@ -1,16 +1,20 @@ -#include - -#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 + + diff --git a/lladd/operations/arrayList.h b/lladd/operations/arrayList.h index 48cdf6e..5ae28d2 100644 --- a/lladd/operations/arrayList.h +++ b/lladd/operations/arrayList.h @@ -1,16 +1,58 @@ -#include +/*--- +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 -#define __ARRAY_LIST_H +The authors hereby grant permission to use, copy, modify, distribute, +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(); diff --git a/lladd/operations/decrement.h b/lladd/operations/decrement.h index 1f0bb80..2a80d91 100644 --- a/lladd/operations/decrement.h +++ b/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 - #define Tdecrement(xid,rid) Tupdate(xid,rid,0, OPERATION_DECREMENT) Operation getDecrement(); diff --git a/lladd/operations/increment.h b/lladd/operations/increment.h index 735e3ed..48cfd19 100644 --- a/lladd/operations/increment.h +++ b/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 - #define Tincrement(xid,rid) Tupdate(xid,rid,0, OPERATION_INCREMENT) Operation getIncrement(); diff --git a/lladd/operations/instantSet.h b/lladd/operations/instantSet.h index ed8ec60..625fa8a 100644 --- a/lladd/operations/instantSet.h +++ b/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 - #define TinstantSet(xid,rid,dat) Tupdate(xid,rid,dat, OPERATION_INSTANT_SET) Operation getInstantSet(); diff --git a/lladd/operations/linearHash.h b/lladd/operations/linearHash.h index 3eda00c..d5d9afc 100644 --- a/lladd/operations/linearHash.h +++ b/lladd/operations/linearHash.h @@ -1,16 +1,21 @@ -#include - -#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) ; diff --git a/lladd/operations/linearHashNTA.h b/lladd/operations/linearHashNTA.h index bee2acd..4b50f90 100644 --- a/lladd/operations/linearHashNTA.h +++ b/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. */ diff --git a/lladd/operations/linkedListNTA.h b/lladd/operations/linkedListNTA.h index 2d0e29e..2e3d035 100644 --- a/lladd/operations/linkedListNTA.h +++ b/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 { diff --git a/lladd/operations/lladdhash.h b/lladd/operations/lladdhash.h index 70253d7..401b91f 100644 --- a/lladd/operations/lladdhash.h +++ b/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 - #ifndef __LLADDHASH_H__ #define __LLADDHASH_H__ diff --git a/lladd/operations/naiveLinearHash.h b/lladd/operations/naiveLinearHash.h index 7d21c24..c30ec13 100644 --- a/lladd/operations/naiveLinearHash.h +++ b/lladd/operations/naiveLinearHash.h @@ -1,16 +1,19 @@ -#include - -#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) ; diff --git a/lladd/operations/nestedTopActions.h b/lladd/operations/nestedTopActions.h index 536c04b..416cd66 100644 --- a/lladd/operations/nestedTopActions.h +++ b/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 - * require any extra logging information, and (could someday) support - * reordering. - * - * @see decrement.h + * + * Nested top actions provide atomic updates to multiple pages within + * a single transaction. LLADD's nested top actions may be nested + * within each other. * * @ingroup OPERATIONS * @@ -59,7 +56,6 @@ terms specified in this license. #ifndef __NESTED_TOP_ACTIONS_H__ #define __NESTED_TOP_ACTIONS_H__ -#include void initNestedTopActions(); void * TbeginNestedTopAction(int xid, int op, const byte* log_arguments, int log_arguments_length); lsn_t TendNestedTopAction(int xid, void * handle); diff --git a/lladd/operations/noop.h b/lladd/operations/noop.h index fc71a2a..f19f016 100644 --- a/lladd/operations/noop.h +++ b/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 - Operation getNoop(); #endif diff --git a/lladd/operations/pageOperations.h b/lladd/operations/pageOperations.h index a514ea6..3720afc 100644 --- a/lladd/operations/pageOperations.h +++ b/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 - * require any extra logging information, and (could someday) support - * reordering. + * Provides raw access to entire pages. * - * @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 - /** If defined, then pageOperations.h will reuse freed pages. Unfortunately, the current support is not safe for programs with multiple concurrent transactions. */ diff --git a/lladd/operations/prepare.h b/lladd/operations/prepare.h index edbc5aa..cff9517 100644 --- a/lladd/operations/prepare.h +++ b/lladd/operations/prepare.h @@ -40,8 +40,11 @@ permission to use and distribute the software in accordance with the terms specified in this license. ---*/ /** - * @file - * Prepare pseudo-operation + * @file + * + * 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 -#include +//#include 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) diff --git a/lladd/operations/set.h b/lladd/operations/set.h index 5599f36..5baa0d6 100644 --- a/lladd/operations/set.h +++ b/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 - +/** + 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); diff --git a/src/lladd/operations/alloc.c b/src/lladd/operations/alloc.c index c79ddc1..490c2f8 100644 --- a/src/lladd/operations/alloc.c +++ b/src/lladd/operations/alloc.c @@ -1,7 +1,7 @@ #include #include -#include +#include #include #include #include "../blobManager.h" diff --git a/src/lladd/operations/decrement.c b/src/lladd/operations/decrement.c index 7f3ed73..97fc715 100644 --- a/src/lladd/operations/decrement.c +++ b/src/lladd/operations/decrement.c @@ -45,8 +45,7 @@ terms specified in this license. * Decrements the given reference by one *********************************************/ -#include -/*#include */ +#include #include "../page.h" static int operate(int xid, Page * p, lsn_t lsn, recordid r, const void *d) { diff --git a/src/lladd/operations/increment.c b/src/lladd/operations/increment.c index 780ecb0..7fa402d 100644 --- a/src/lladd/operations/increment.c +++ b/src/lladd/operations/increment.c @@ -45,8 +45,7 @@ terms specified in this license. * Increments the given reference by one **********************************************/ -#include -/*#include */ +#include #include "../page.h" static int operate(int xid, Page * p, lsn_t lsn, recordid r, const void *d) { diff --git a/src/lladd/operations/instantSet.c b/src/lladd/operations/instantSet.c index 3891825..04eafff 100644 --- a/src/lladd/operations/instantSet.c +++ b/src/lladd/operations/instantSet.c @@ -45,8 +45,7 @@ terms specified in this license. * sets the given reference to dat **********************************************/ -#include -#include +#include #include "../page.h" #include "../page/fixed.h" diff --git a/src/lladd/operations/linearHash.c b/src/lladd/operations/linearHash.c index 7cd092a..ae2c988 100644 --- a/src/lladd/operations/linearHash.c +++ b/src/lladd/operations/linearHash.c @@ -1,5 +1,5 @@ -#include +#include #include #include #include diff --git a/src/lladd/operations/lladdhash.c b/src/lladd/operations/lladdhash.c index 7da5782..1fba05e 100644 --- a/src/lladd/operations/lladdhash.c +++ b/src/lladd/operations/lladdhash.c @@ -1,8 +1,7 @@ #include #include -#include -#include +#include #include #include diff --git a/src/lladd/operations/naiveLinearHash.c b/src/lladd/operations/naiveLinearHash.c index 42c0a8a..69b59cb 100644 --- a/src/lladd/operations/naiveLinearHash.c +++ b/src/lladd/operations/naiveLinearHash.c @@ -1,4 +1,4 @@ -#include +#include #include #include #include diff --git a/src/lladd/operations/noop.c b/src/lladd/operations/noop.c index f208d7e..a8912fd 100644 --- a/src/lladd/operations/noop.c +++ b/src/lladd/operations/noop.c @@ -45,7 +45,7 @@ terms specified in this license. * sets the given reference to dat **********************************************/ -#include +#include #include "../page.h" static int operate(int xid, Page *p, lsn_t lsn, recordid rid, const void *dat) { diff --git a/src/lladd/operations/prepare.c b/src/lladd/operations/prepare.c index 173b17b..8dacfdd 100644 --- a/src/lladd/operations/prepare.c +++ b/src/lladd/operations/prepare.c @@ -46,7 +46,7 @@ terms specified in this license. * sets the given reference to dat **********************************************/ -#include +#include #include "../logger/logWriter.h" #include #include diff --git a/src/lladd/operations/set.c b/src/lladd/operations/set.c index 08e9505..c772b68 100644 --- a/src/lladd/operations/set.c +++ b/src/lladd/operations/set.c @@ -45,8 +45,7 @@ terms specified in this license. * sets the given reference to dat **********************************************/ -#include -/*#include */ +#include #include "../page.h" #include #include diff --git a/src/lladd/page.c b/src/lladd/page.c index 0e6e4fa..c089a12 100644 --- a/src/lladd/page.c +++ b/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. diff --git a/src/lladd/page.h b/src/lladd/page.h index b9aff0a..f6e356a 100644 --- a/src/lladd/page.h +++ b/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 - * wish to write + * @param page a pointer to an in-memory copy of the page as it + * 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