docs/Samba-Developers-Guide/gencache.xml

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3                 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
   4   <!ENTITY % global_entities SYSTEM '../entities/global.entities'>
   5   %global_entities;
   6 ]>
   7
   8 <chapter id="gencache">
   9 <chapterinfo>
  10         <author>
  11                 <firstname>Rafal</firstname><surname>Szczesniak</surname>
  12         </author>
  13         <pubdate>April 2003</pubdate>
  14 </chapterinfo>
  15
  16 <title>General cache mechanism and API</title>
  17
  18 <sect1>
  19 <title>Abstract</title>
  20 <para>
  21 General cache (gencache) was designed to combine various kinds of caching
  22 mechanisms into one, defined by a simple API. This way, anyone can use it
  23 to create their own caching layer on top of gencache. An example of
  24 such approach is the netbios name cache.
  25 </para>
  26 </sect1>
  27
  28 <sect1>
  29 <title>The mechanism</title>
  30 <para>
  31 Gencache utilises <emphasise>tdb</emphasise> database, like many other
  32 parts of Samba. As its origins are in Berkeley DB implementation, it
  33 uses key/value pairs stored in binary file. The values gencache
  34 operates on are string-based, however. This makes very easy to use it
  35 in command line environment eg. to quickly take a look at what's in
  36 the cache or set some value.
  37 </para>
  38
  39 <para>
  40 All the data is stored in <filename>gencache.tdb</filename>
  41 file. Records put there are in key/value format as mentioned below,
  42 but as it's a cache, the timeout plays also important role and has a
  43 special place in the key/value pair, as well as API.
  44 </para>
  45 </sect1>
  46
  47
  48 <sect1>
  49 <title>The data structure</title>
  50 <para>
  51 The record stored in <filename>gencache.tdb</filename> file consists
  52 of the key, the value and the expiration timeout. While the first part
  53 is stored completely independent from the others, the last two are
  54 kept together. The form the record has is:
  55 </para>
  56
  57 <para><programlisting>
  58 key:     &lt;string&gt;
  59 value:   &lt;12-digit timeout&gt;/&lt;string&gt;
  60 </programlisting></para>
  61
  62 <para>The timeout part is the ASCII representation of
  63 <emphasis>time_t</emphasis> value of the time when the cache entry
  64 expires. Obviously the API, the programmer is provided with, hides this detail,
  65 so that you don't have to care about checking it. Simply watch
  66 carefully the return status of the function.
  67 </para>
  68 </sect1>
  69
  70 <sect1>
  71 <title>The API</title>
  72
  73 <para><programlisting>
  74 BOOL gencache_init()
  75 </programlisting></para>
  76
  77 <para>This is used to initialise to whole caching mechanism. It means
  78 opening the file or creating it if non-existing. If it's already been
  79 opened earlier, then the routine just does nothing and returns
  80 <constant>true</constant>. If something goes wrong, say the user
  81 doesn't have necessary rights, the function returns
  82 <constant>false</constant>.</para>
  83
  84 <para><programlisting>
  85 BOOL gencache_shutdown()
  86 </programlisting></para>
  87
  88 <para>This is the proper way to close the cache file. It simply
  89 returns <constant>true</constant> after successful closing file and
  90 <constant>false</constant> upon a failure.</para>
  91
  92 <para><programlisting>
  93 BOOL gencache_set(const char* keystr, const char* value, time_t timeout)
  94 </programlisting></para>
  95
  96 <para>This is one of the most basic functions. What it allows you to
  97 do is to set some particular cache entry. If the entry haven't
  98 existed yet, the function will act just as it was "gencache_add"
  99 function. If it's already been in the cache, the entry will be set to
 100 the new value. In either case, the cache entry will be set with given
 101 key, value and timeout. Thus it is comfortable way to just set the
 102 entry and not care about the details.</para>
 103
 104 <para><programlisting>
 105 BOOL gencache_set_only(const char* keystr, const char* value, time_t timeout)
 106 </programlisting></para>
 107
 108 <para><programlisting>
 109 BOOL gencache_del(const char* keystr)
 110 </programlisting></para>
 111
 112 <para><programlisting>
 113 BOOL gencache_get(const char* keystr, char** valstr, time_t* timeout)
 114 </programlisting></para>
 115
 116 <para><programlisting>
 117 void gencache_iterate(void (*fn)(const char* key, const char *value, time_t timeout, void* dptr),
 118                       void* data, const char* keystr_pattern)
 119
 120 </programlisting></para>
 121
 122 </sect1>
 123
 124 </chapter>