VENTI-CACHE(3)                                     VENTI-CACHE(3)

     NAME
          VtBlock, VtCache, vtblockcopy, vtblockduplock, vtblockput,
          vtblockwrite, vtcachealloc, vtcacheallocblock, vtcachefree,
          vtcacheglobal, vtcachelocal, vtcachesetwrite,
          vtglobaltolocal, vtlocaltoglobal - Venti block cache

     SYNOPSIS
          #include <u.h>
          #include <libc.h>
          #include <venti.h>

          typedef struct VtBlock
          {
               uchar *data;
               uchar type;
               uchar score[VtScoreSize];
               u32int addr;
               ...
          } VtBlock;

          VtCache* vtcachealloc(VtConn *z, ulong maxmem);

          void     vtcachefree(VtCache *c);

          u32int   vtglobaltolocal(uchar score[VtScoreSize])
          void     vtlocaltoglobal(u32int local, uchar score[VtScoreSize])

          VtBlock* vtcacheallocblock(VtCache *c, int type, ulong size);

          VtBlock* vtcachelocal(VtCache *c, u32int addr, int type);

          VtBlock* vtcacheglobal(VtCache *c, uchar[VtScoreSize], int type, ulong size);

          void     vtblockput(VtBlock *b);

          void     vtblockduplock(VtBlock *b);

          int      vtblockwrite(VtBlock *b);

          void     vtcachesetwrite(VtCache *c,
                      int (*write)(VtConn*, uchar[VtScoreSize], uint, uchar*, int));

          VtBlock* vtblockcopy(VtBlock *b);

     DESCRIPTION
          These functions provide access to a simple in-memory cache
          of blocks already stored on a Venti server and blocks that
          will eventually be stored on a Venti server.

          A VtBlock represents a venti data block.  Blocks stored on a

     VENTI-CACHE(3)                                     VENTI-CACHE(3)

          venti server, called global blocks, are named by the SHA1
          hash of their contents.  This hash is recorded as the
          block's score. Such blocks are immutable.  The cache also
          stores mutable blocks that have not yet been written to a
          venti server.  These blocks are called local blocks, and
          have special scores that are 16 zero bytes followed by a 4-
          byte big-endian address. The address is an index into the
          internal set of cache blocks.

          The user-visible contents of a VtBlock are data, a pointer
          to the data; type, the venti block type; score, the block's
          score; and addr, the block's cache address.

          Vtcachealloc allocates a new cache using the client connec-
          tion z (see venti-conn(3) and venti-client(3)), with maxmem
          bytes of memory.

          Vtcachefree frees a cache and all the associated blocks.

          Vtglobaltolocal returns the local address corresponding to
          the given local score. If passed a global score,
          vtglobaltolocal returns the special constant NilBlock (~0).
          Vtlocaltoglobal is the opposite, setting score to the local
          score for the cache address local.

          Vtcacheallocblock allocates a new local block with the given
          type and size.

          Vtcachelocal retrieves the local block at address addr from
          the cache.  The given type must match the type of the block
          found at addr.

          Vtcacheglobal retrieves the block with the given score,
          dtype and size from the cache, consulting the Venti server
          if necessary.  If passed a local score, vtcacheglobal
          invokes vtcachelocal appropriately.

          The block references returned by vtcacheallocblock,
          vtcachelocal, and vtcacheglobal must be released when no
          longer needed.  Vtblockput releases such a reference.

          It is occasionally convenient to have multiple variables
          refer to the same block.  Vtblockduplock increments the
          block's reference count so that an extra vtblockput will be
          required in order to release the block.

          Vtblockwrite writes a local block to the Venti server,
          changing the block to a global block.  It calls the cache's
          write function to write the block to the server.  The
          default write function is vtwrite (see venti-client(3));
          vtsetcachewrite sets it.  Vtsetcachewrite is used by clients
          to install replacement functions that run writes in the

     VENTI-CACHE(3)                                     VENTI-CACHE(3)

          background or perform other additional processing.

          Vtblockcopy copies a block in preparation for modifying its
          contents.  The old block may be a local or global block, but
          the new block will be a local block.

          The cache only evicts global blocks.  Local blocks can only
          leave the cache via vtblockwrite, which turns them into glo-
          bal blocks, making them candidates for eviction.

          If a new cache block must be allocated (for
          vtcacheallocblock, vtcachelocal, vtcacheglobal, or
          vtblockcopy), but the cache is filled (with local blocks and
          blocks that have not yet been released with vtblockput), the
          library prints the score and reference count of every block
          in the cache and then aborts.  A full cache indicates either
          that the cache is too small, or, more commonly, that cache
          blocks are being leaked.

     SOURCE
          /src/libventi

     SEE ALSO
          venti(3), venti-client(3), venti-conn(3), venti-file(3),
          venti(7)