2nd August 1988 : new buffer manager interface and comments
(unratified)

Author : Jeff Goh

the new buffer manager maintains buffers in shared memory,
using a single semaphore to enforce consistency.  This has
proved to be satisfactory since consistency problems
between backends are addressed largely by the lock-manager,
so the buffer manager only needs to control inter-backend
access to the control structures.  Operations on control
structures rarely take more than a few milliseconds, so
this seems acceptable (at least for now).

buffer manager : shared structure 
(temporary, will change )

size of the shared memory segment is governed by the following
parameters :
NDBUFS = number of disk buffers on startup
BLCKSZ = disk block size, currently hardwired to 8K.
sizeof(Sbufdesc) = size of the shared buffer descriptors.

the size is NDBUFS*BLCKSZ + (NDBUFS+1)*sizeof(Sbufdesc)
the extra shared buffer descriptor being the list head.

************

Interface :

the interface will be governed by 4 functions :

ReadBuffer(reln,blknum,flags)
	Relation reln;
	BlockNumber blknum;
	BufFlags flags;
   - reads a buffer into shared memory, pin it by default and
     then return an index into the local buffer-descriptor-array
     to the calling routine.
   - increments reference count on buffer

WriteBuffer(buffer)
	Buffer bufer;
  - if LATEWRITE is set then schedule the page for writing 
    by marking it as dirty, actual writing will take place
    when page needs to be paged out.
  - if LATEWRITE not set, behaviour like FlushBuffer.
  - decrements reference count on buffer  

WriteNoRelease(buffer)
	Buffer buffer;
  - does just what its names suggests
  - does not affect pin-counts (refcounts)
    either locally or globally

FlushBuffer(buffeR)
	Buffer buffer;
  - Always write out the buffer immedately, blocking until the
    physical write is done.  This is the behaviour
    exhibited by WriteBuffer #ifndef LATEWRITE
  - decrements reference count on buffer

ReleaseBuffer(buffeR)
        Buffer buffer;
  - Decrement the reference count locally and in shared memory.
    if local_count = 0, free the local descriptor.  If shared
    count also hits zero, then buffer is put on Shared Free List.

BufferManagerFlush()
  - flush all buffers pinned by this process to disk
    decrementing the reference count, freeing buffers
    as necessary.  Called by AbortTransaction, CommitTransaction
    amongst other things.

IMPORTANT NOTE TO ACCESS METHOD implementors :

  ReadBuffer calls should be balanced by one of WriteBuffer,
  ReleaseBuffer or FlushBuffer as soon as the buffer is not needed.