doc/pod/libinnhist.pod

   1 =head1 NAME
   2
   3 his - routines for managing INN history
   4
   5 =head1 SYNOPSIS
   6
   7 B<#include E<lt>inn/history.hE<gt>>
   8
   9 B<struct history;>
  10
  11 B<struct histstats {>
  12 B<    int hitpos;>
  13 B<    int hitneg;>
  14 B<    int misses;>
  15 B<    int dne;>
  16 B<};>
  17
  18 B<#define HIS_RDONLY ...>
  19 B<#define HIS_RDWR ...>
  20 B<#define HIS_CREAT ...>
  21 B<#define HIS_ONDISK ...>
  22 B<#define HIS_INCORE ...>
  23 B<#define HIS_MMAP ...>
  24
  25 B<enum {>
  26 B<    HISCTLG_PATH,>
  27 B<    HISCTLS_PATH,>
  28 B<    HISCTLS_SYNCCOUNT,>
  29 B<    HISCTLS_NPAIRS,>
  30 B<    HISCTLS_IGNOREOLD,>
  31 B<    HISCTLS_STATINTERVAL>
  32 B<};>
  33
  34 B<struct history *HISopen(const char *>I<path>B<, const char *>I<method>B<, int >I<flags>B<);>
  35
  36 B<bool HISclose(struct history *>I<history>B<);>
  37
  38 B<bool HISsync(struct history *>I<history>B<);>
  39
  40 B<void HISsetcache(struct history *>I<history>B<, size_t >I<size>B<);>
  41
  42 B<bool HISlookup(struct history *>I<history>B<, const char *>I<key>B<, time_t *>I<arrived>B<, time_t *>I<posted>B<, time_t *>I<expires>B<, TOKEN *>I<token>B<);>
  43
  44 B<bool HIScheck(struct history *>I<history>B<, const char *>I<key>B<);>
  45
  46 B<bool HISwrite(struct history *>I<history>B<, const char *>I<key>B<, time_t >I<arrived>B<, time_t >I<posted>B<, time_t >I<expires>B<, const TOKEN *>I<token>B<);>
  47
  48 B<bool HISremember(struct history *>I<history>B<, const char *>I<key>B<, time_t >I<arrived>B<);>
  49
  50 B<bool HISreplace(struct history *>I<history>B<, const char *>I<key>B<, time_t >I<arrived>B<, time_t >I<posted>B<, time_t >I<expires>B<, const TOKEN *>I<token>B<);>
  51
  52 B<bool HISexpire(struct history *>I<history>B<, const char *>I<path>B<, const char *>I<reason>B<, bool >I<writing>B<, void *>I<cookie>B<, time_t >I<threshold>B<, bool (*>I<exists>B<)(void *cookie, time_t arrived, time_t posted, time_t expires, const TOKEN *token));>
  53
  54 B<bool HISwalk(struct history *>I<history>B<, const char *>I<reason>B<, void *>I<cookie>B<, bool (*>I<callback>B<)(void *cookie, time_t arrived, time_t posted, time_t expires, const TOKEN *token));>
  55
  56 B<struct histstats HISstats(struct history *>I<history>B<);>
  57
  58 B<const char *HISerror(struct history *>I<history>B<);>
  59
  60 B<bool HISctl(struct history *>I<history>B<, int >I<request>B<, void *>I<val>B<);>
  61
  62 =head1 DESCRIPTION
  63
  64 These functions provide provide access to the INN history
  65 database. They maintain key/value pairs in an opaque database whilst
  66 providing for expiry of outdated information.
  67
  68 The history structure is an opaque handle returned from HISopen.
  69
  70 The B<HISopen> function opens the history file designated by I<path>
  71 using the mode I<flags> using the specified I<method>. I<flags> may be
  72 B<HIS_RDONLY> to indicate that read-only access to the history
  73 database is desired, or B<HIS_RDWR> for read/write access. History
  74 methods are defined at build time; the history method currently
  75 available is "hisv6". On success a newly initialised history handle is
  76 returned, or B<NULL> on failure.
  77
  78 B<HIS_ONDISK>, B<HIS_INCORE> and B<HIS_MMAP> may be logically ORed
  79 into I<flags> to provide a hint to the underlying history manager as
  80 to how it should handle its data files; B<HIS_ONDISK> indicates that
  81 the caller would like as much of the data to be kept on disk (and out
  82 of memory), B<HIS_INCORE> indicates that the data files should be kept
  83 in main memory where possible and B<HIS_MMAP> that the files should be
  84 mmap()ed into the processes address space. B<HIS_INCORE> is typically
  85 used where a mass rebuild of the history database is being performed;
  86 the underlying history manager may assume that the caller will call
  87 B<HISsync>() to sync the data files to disk.
  88
  89 The B<HIS_CREAT> flag indicates that the history database should be
  90 initialised as new; if any options which affect creation of the
  91 database need to be set an anonymous history handle should be created
  92 by calling B<HISopen> with I<path> set to B<NULL>, any options set
  93 using B<HISctl>, then the database opened by calling B<HISctl> with
  94 B<HISCTLS_PATH>.
  95
  96 The B<HISclose> function closes the handle I<history> and deallocates
  97 any resources associated with it. It returns B<false> on failure or
  98 B<true> on success.
  99
 100 The B<HISsync> function synchronises any outstanding transactions
 101 associated with I<history> to disk.
 102
 103 B<HISsetcache> associates a cache used for speeding up HIScheck with
 104 I<history>. The cache will occupy approximately I<size> bytes.
 105
 106 B<HISlookup> retrieves a token from I<history> based on the passed
 107 I<key> (normally the Message-ID). If no entry with an associated token
 108 can be found, B<HISlookup> will return B<false>. If a token is found
 109 I<arrived>, I<expires>, and I<posted> are filled in with the message
 110 arrival, expiry, and posting times respectively (or zero, if the time
 111 component is not available), in addition to I<token> being set to the
 112 retrieved token and a function return value of B<true>. Any of
 113 arrived, expires, posted, or token may be B<NULL> in which case that
 114 component is not returned to the caller, without affecting the return
 115 value.
 116
 117 B<HIScheck> checks the database I<history> for I<key> (normally the
 118 Message-ID); if I<key> has previously been set via B<HISwrite>,
 119 B<HIScheck> returns B<true>, else B<false>.
 120
 121 B<HISwrite> writes a new entry to the database I<history> associated
 122 with I<key>. I<arrived>, I<posted>, and I<expired> specify the arrival,
 123 posting, and expiry time respectively; I<posted> and I<expired> may be
 124 specifed as <= 0 in which case that component shall be treated as
 125 absent in the database. I<token> is associated with the specified
 126 I<key>. B<HISwrite> returns B<true> on success, or B<false> on
 127 failure. The behaviour when I<key> is not unique with respect to the
 128 existing entries in I<history> is unspecified.
 129
 130 B<HISremember> writes a new entry to the database I<history>
 131 associated with I<key>, merely remembering that this I<key> has been
 132 seen, together with its arrival time I<arrived>. B<HISremember>
 133 returns B<true> on success, or B<false> on failure. The behaviour when
 134 I<key> is not unique with respect to the existing entries in
 135 I<history> is unspecified.
 136
 137 B<HISreplace> replaces an existing entry in the database I<history>,
 138 associated with I<key>. I<arrived>, I<posted>, I<expired> specify the
 139 arrival, posting and expiry time respectively; I<posted> and
 140 I<expired> may be specifed as <= 0 in which case that component shall
 141 be treated as absent in the database. I<token> is associated with the
 142 specified I<key>; if B<NULL> then the history database merely
 143 remembers that this I<key> has been seen, together with its arrival
 144 time. B<HISreplace> returns B<true> on success, or B<false> on
 145 failure.
 146
 147 B<HISexpire> expires the history database associated with I<history>,
 148 creating a new, replacement, database in the same location if I<path>
 149 is B<NULL>, or in I<path> if not B<NULL>; if I<path> is not B<NULL>
 150 then the replacement of the old history database with the new one is
 151 assumed to be performed out of band by the caller. The I<writing> flag
 152 is normally passed as B<true>, if you wish to inhibit writing of the
 153 new database (and so merely see the callbacks), I<writing> may be set
 154 B<false>.
 155
 156 If the underlying history mechanism needs to pause the server, the
 157 I<reason> string is used as the argument to the `ctlinnd pause'
 158 command, and as such the server should be reserved by the caller prior
 159 to calling B<HISexpire>; if the caller wishes to inhibit pausing of
 160 the server, passing B<NULL> will achieve this. If I<reason> is not
 161 B<NULL>, then on successful return from B<HISexpire> the server will
 162 be left paused and the caller should unpause it.
 163
 164 The history database is scanned and entries with an associated storage
 165 token are passed to the discrimination function I<exists>.
 166
 167 If I<exists>() returns B<false> it indicates that stored entity
 168 associated with token is no longer available (or no longer required),
 169 and therefore the associated history entry may be expired once it
 170 meets the I<threshold> constraint. If I<exists>() returns B<true> the
 171 entry is kept as-is in the newly expired history database.
 172
 173 The I<exists> function is passed the arrival, posting and expiry
 174 times, in addition to the token associated with the entry. Note that
 175 posting and/or expiry may be zero, but that the token will never be
 176 B<NULL> (such entries are handled solely via the threshold
 177 mechanism). The storage token passed to the discrimination function
 178 may updated if required (for example, as might be needed by a
 179 hierachical storage management implementation).
 180
 181 Entries in the database with an arrival time less than I<threshold>
 182 with no token associated with them are deleted from the database.
 183
 184 The parameter I<cookie> is passed to the discrimination function, and
 185 may be used for any purpose required by the caller.
 186
 187 If the discrimination function attempts to access the underlying
 188 database (for read or write) during the callback, the behaviour is
 189 unspecified.
 190
 191 B<HISwalk> provides an iteration function for the specified I<history>
 192 database. For every entry in the history database, I<callback> is
 193 invoked, passing the I<cookie>, arrival, posting, and expiry times, in
 194 addition to the token associated with the entry. If the I<callback>()
 195 returns B<false> the iteration is aborted and B<HISwalk> returns
 196 B<false> to the caller.
 197
 198 To process the entire database in the presence of a running server,
 199 I<reason> may be passed; if this argument is not B<NULL>, it is used
 200 as an an argument to the `ctlinnd (reserve|pause|go)' commands. If
 201 I<reason> is B<NULL> and the server is running, the behaviour of
 202 B<HISwalk> is undefined.
 203
 204 If the callback function attempts to access the underlying database
 205 during the callback, the behaviour is unspecified.
 206
 207 B<HISstats> returns statistics on the history cache mechanism; given a
 208 handle I<history>, the return value is a I<struct histstats>
 209 detailing:
 210
 211 =over 4
 212
 213 =item C<hitpos>
 214
 215 The number of times an item was found directly in the cache and known
 216 to exist in the underlying history manager.
 217
 218 =item C<hitneg>
 219
 220 The number of times an item was found directly in the cache and known
 221 not to exist in the underlying history manager.
 222
 223 =item C<misses>
 224
 225 The number of times an item was not found directly in the cache, but
 226 on retrieval from the underlying history manager was found to exist.
 227
 228 =item C<dne>
 229
 230 The number of times an item was not found directly in the cache, but
 231 on retrieval from the underlying history manager was found not to exist.
 232
 233 =back
 234
 235 Note that the history cache is only checked by B<HIScheck> and only
 236 affected by B<HIScheck>, B<HISwrite>, B<HISremember> and
 237 B<HISreplace>. Following a call to B<HISstats> the history statistics
 238 associated with I<history> are cleared.
 239
 240 B<HISerror> returns a string describing the most recent error
 241 associated with I<history>; the format and content of these strings is
 242 history manager dependent. Note that on setting an error, the history
 243 API will call the B<warn> function from libinn(3).
 244
 245 B<HISctl> provides a control interface to the underlying history
 246 manager. The I<request> argument determines the type of the request
 247 and the meaning of the I<val> argument. The values for I<request> are:
 248
 249 =over 4
 250
 251 =item C<HISCTLG_PATH> (const char **)
 252
 253 Get the base file path which the history handle represents. I<val>
 254 should be a pointer to a location of type B<const char *>.  The
 255 result must not later be passed to free(3).
 256
 257
 258 =item C<HISCTLS_PATH> (const char *)
 259
 260 Set the base file path which this history handle should use; typically
 261 this is used after an anonymous handle has been created using
 262 B<HISopen(NULL, ...)>. I<val> should be a value of type B<const char
 263 *> and will be copied before being stored internally.
 264
 265 =item C<HISCTLS_SYNCCOUNT> (size_t *)
 266
 267 Set an upper bound on how many history operations may be pending in
 268 core before being synced to permanent storage; B<0> indicates
 269 unlimited. I<val> should be a pointer to a value of type B<size_t> and
 270 will not be modified by the call.
 271
 272 =item C<HISCTLS_NPAIRS> (size_t *)
 273
 274 Set a hint to the to the underlying history manager as to how many
 275 entries there are expected to be in the history database; B<0>
 276 indicates that an automatic or default sizing should be made. I<val>
 277 should be a pointer to a value of type B<size_t> and will not be
 278 modified by the call.
 279
 280 =item C<HISCTLS_IGNOREOLD> (bool *)
 281
 282 Instruct the underlying history manager to ignore existing database
 283 when creating new ones; typically this option may be set to B<true> if
 284 the administrator believes that the existing history database is
 285 corrupt and that ignoring it may help. I<val> should be a pointer to a
 286 value of type B<bool> and will not be modified by the call.
 287
 288 =item C<HISCTLS_STATINTERVAL> (time_t *)
 289
 290 For the history v6 and tagged hash managers, set the interval, in
 291 seconds, between stat(2)s of the history files checking for replaced
 292 files (as happens during expire); this option is typically used by
 293 nnrpd(8) like applications. I<val> should be a pointer to a value of
 294 type B<time_t> and will not be modified by the call.
 295
 296 =head1 HISTORY
 297
 298 Written by Alex Kiernan <alexk@demon.net> for InterNetNews 2.4.0.
 299
 300 $Id: libinnhist.pod 5909 2002-12-03 05:17:18Z vinocur $