More documentation fixes.

lladd/bufferManager.h

@@ -148,9 +148,13 @@ recordid ralloc(int xid, long size);
 long readLSN(int pageid);
 
 /**
- * @param xid transaction id
- * @param rid recordid where you want to write
- * @param dat data you wish to write
+ * @param xid transaction id @param lsn the lsn that the updated
+ * record will reflect.  This is needed by recovery, and undo.  (The
+ * 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
  */
 void writeRecord(int xid, lsn_t lsn, recordid rid, const void *dat);
 
@@ -168,7 +172,7 @@ void readRecord(int xid, recordid rid, void *dat);
  * to see if some other page can be kicked, in order to avoid the log
  * flush.  
  *
- * @param page  The page to be flushed to disk.
+ * @param dat  The page to be flushed to disk.
  */
 void pageWrite(const Page * dat);
 
@@ -176,8 +180,8 @@ void pageWrite(const Page * dat);
 /**
    Read a page from disk.  
 
-   @param A page struct, with id set correctly.  The rest of this
-   struct is filled out by pageMap.
+   @param ret A page struct, with id set correctly.  The rest of this
+   struct will be overwritten by pageMap.
 */
 void pageRead(Page * ret);
 
@@ -203,6 +207,9 @@ int dropPage(Page page);
  * it might be useful when locking is implemented.
  *
  * @param xid transaction ID
+ * @param lsn the lsn at which the transaction aborted.  (Currently
+ * unused, but may be useful for other implementations of the buffer
+ * manager.)
  * @return 0 on success
  * @return error code on failure
  */
@@ -212,8 +219,14 @@ int bufTransCommit(int xid, lsn_t lsn);
  * 
  * Currently identical to bufTransCommit.
  * 
- * @param xid transaction ID
+ * @param xid transaction ID 
+ * 
+ * @param lsn the lsn at which the transaction aborted.  (Currently
+ * unused, but may be useful for other implementations of the buffer
+ * manager.)
+ *
  * @return 0 on success
+ *  
  * @return error code on failure
  */
 int bufTransAbort(int xid, lsn_t lsn);
@@ -224,10 +237,4 @@ int bufTransAbort(int xid, lsn_t lsn);
  */
 void bufDeinit();
 
-/** @todo Global file descriptors are nasty. */
-
-extern int blobfd0;
-extern int blobfd1;
-
-
 #endif

lladd/logger/logEntry.h

@@ -59,6 +59,8 @@ BEGIN_C_DECLS
    
    @todo Is there a better way to deal with sizeof() and log entries?
    
+   @todo Other than some typedefs, is there anything in logEntry that belongs in the API?
+
    @ingroup LLADD_CORE
    
    $Id$

lladd/operations.h

@@ -46,6 +46,7 @@ terms specified in this license.
  * Interface for defining new logical operations.
  *
  * @ingroup LLADD_CORE OPERATIONS
+ * @todo The functions in operations.h don't belong in the API, but it defines some constants and typedefs that should be there.
  * $Id$
  */
 

lladd/page.h

@@ -98,7 +98,156 @@ void pageWriteLSN(Page page);
  * as a parameter a Page and returns the LSN that is currently written on that
  * page in memory.
  */
-long pageReadLSN(Page page);
+lsn_t/*---
+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.
+
+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
+ *
+ * interface for dealing with slotted pages
+ *
+ * @ingroup LLADD_CORE
+ * $Id$
+ * 
+ * @todo update docs in this file.
+ **/
+
+#ifndef __PAGE_H__
+#define __PAGE_H__
+
+#include "common.h"
+
+BEGIN_C_DECLS
+
+/**
+ * represents how to look up a record on a page
+ */
+typedef struct {
+  int page;
+  int slot;
+  long size;
+} recordid;
+
+
+typedef struct Page_s {
+	int id;
+	long LSN;
+	byte *memAddr;
+	int dirty;
+	struct Page_s *next;
+        /** for replacement policy */
+	struct Page_s *prev; 
+        /** this too */
+	int queue; 
+} Page;
+
+/**
+ * initializes all the important variables needed in all the
+ * functions dealing with pages.
+ */
+void pageInit();
+
+/**
+ * assumes that the page is already loaded in memory.  It takes
+ * as a parameter a Page.  The Page struct contains the new LSN and the page
+ * number to which the new LSN must be written to.
+ */
+void pageWriteLSN(Page page);
+
+/**
+ * assumes that the page is already loaded in memory.  It takes
+ * as a parameter a Page and returns the LSN that is currently written on that
+ * page in memory.
+ */
+lsn_t pageReadLSN(Page page);
+
+/**
+ * assumes that the page is already loaded in memory.  It takes as a
+ * parameter a Page, and returns an estimate of the amount of free space on this
+ * page.  This is either exact, or an underestimate.
+ */
+int freespace(Page page);
+
+/**
+ * assumes that the page is already loaded in memory.  It takes as
+ * parameters a Page and the size in bytes of the new record.  pageRalloc()
+ * returns a recordid representing the newly allocated record.
+ *
+ * NOTE: might want to pad records to be multiple of words in length, or, simply
+ *       make sure all records start word aligned, but not necessarily having 
+ *       a length that is a multiple of words.  (Since Tread(), Twrite() ultimately 
+ *       call memcpy(), this shouldn't be an issue)
+ *
+ * NOTE: pageRalloc() assumes that the caller already made sure that sufficient
+ * amount of freespace exists in this page.  (@see freespace())
+ *
+ * @todo Makes no attempt to reuse old recordid's.
+ */
+recordid pageRalloc(Page page, int size);
+
+void pageWriteRecord(int xid, Page page, recordid rid, const byte *data);
+
+void pageReadRecord(int xid, Page page, recordid rid, byte *buff);
+
+void pageCommit(int xid);
+
+void pageAbort(int xid);
+
+void pageRealloc(Page *p, int id);
+
+Page* pageAlloc(int id);
+
+recordid pageSlotRalloc(Page page, lsn_t lsn, recordid rid);
+
+int pageTest();
+
+int getSlotType(Page p, int slot, int type);
+void setSlotType(Page p, int slot, int type);
+
+
+END_C_DECLS
+
+#endif
+ pageReadLSN(Page page);
 
 /**
  * assumes that the page is already loaded in memory.  It takes as a

src/lladd/bufferManager.c

@@ -297,6 +297,8 @@ void writeRecord(int xid, lsn_t lsn, recordid rid, const void *dat) {
 	  DEBUG("Writing record.\n");
 	  p = loadPagePtr(rid.page);
 	  assert( (p->id == rid.page) && (p->memAddr != NULL) );	
+	  /** @todo This assert should be here, but the tests are broken, so it causes bogus failures. */
+	  /*assert(pageReadLSN(*p) <= lsn);*/
 	  
 	  pageWriteRecord(xid, *p, rid, dat);
 	  /*	  writeLSN(lsn, rid.page); */

src/lladd/page.c

@@ -215,7 +215,7 @@ static const byte *slotMemAddr(const byte *memAddr, int slotNum) {
  * as a parameter a Page and returns the LSN that is currently written on that
  * page in memory.
  */
-long pageReadLSN(Page page) {
+lsn_t pageReadLSN(Page page) {
 	return *(long *)(page.memAddr + START_OF_LSN);
 }