NAME¶
his - routines for managing INN history
SYNOPSIS¶
#include <inn/history.h>
struct history;
struct token;
struct histstats {
int hitpos;
int hitneg;
int misses;
int dne;
};
#define HIS_RDONLY ...
#define HIS_RDWR ...
#define HIS_CREAT ...
#define HIS_ONDISK ...
#define HIS_INCORE ...
#define HIS_MMAP ...
enum {
HISCTLG_PATH,
HISCTLS_PATH,
HISCTLS_SYNCCOUNT,
HISCTLS_NPAIRS,
HISCTLS_IGNOREOLD,
HISCTLS_STATINTERVAL
};
struct history *HISopen(const char *path, const char *method, int flags);
bool HISclose(struct history *history);
bool HISsync(struct history *history);
void HISsetcache(struct history *history, size_t size);
bool HISlookup(struct history *history, const char *key, time_t *arrived, time_t *posted, time_t *expires, TOKEN *token);
bool HIScheck(struct history *history, const char *key);
bool HISwrite(struct history *history, const char *key, time_t arrived, time_t posted, time_t expires, const TOKEN *token);
bool HISremember(struct history *history, const char *key, time_t arrived, time_t posted);
bool HISreplace(struct history *history, const char *key, time_t arrived, time_t posted, time_t expires, const TOKEN *token);
bool HISexpire(struct history *history, const char *path, const char *reason, bool writing, void *cookie, time_t threshold, bool (*exists)(void *cookie, time_t arrived, time_t posted, time_t expires, const TOKEN *token));
bool HISwalk(struct history *history, const char *reason, void *cookie, bool (*callback)(void *cookie, time_t arrived, time_t posted, time_t expires, const TOKEN *token));
struct histstats HISstats(struct history *history);
const char *HISerror(struct history *history);
bool HISctl(struct history *history, int request, void *val);
DESCRIPTION¶
These functions provide access to the INN history database. They maintain
key/value pairs in an opaque database whilst providing for expiry of outdated
information.
The history structure is an opaque handle returned from HISopen.
The
HISopen function opens the history file designated by
path
using the mode
flags using the specified
method.
flags
may be
HIS_RDONLY to indicate that read-only access to the history
database is desired, or
HIS_RDWR for read/write access. History methods
are defined at build time; the history method currently available is
"hisv6". On success a newly initialised history handle is returned,
or
NULL on failure.
HIS_ONDISK,
HIS_INCORE and
HIS_MMAP may be logically ORed
into
flags to provide a hint to the underlying history manager as to
how it should handle its data files;
HIS_ONDISK indicates that the
caller would like as much of the data to be kept on disk (and out of memory),
HIS_INCORE indicates that the data files should be kept in main memory
where possible and
HIS_MMAP that the files should be
mmap()ed
into the processes address space.
HIS_INCORE is typically used where a
mass rebuild of the history database is being performed; the underlying
history manager may assume that the caller will call
HISsync() to sync
the data files to disk.
The
HIS_CREAT flag indicates that the history database should be
initialised as new; if any options which affect creation of the database need
to be set an anonymous history handle should be created by calling
HISopen with
path set to
NULL, any options set using
HISctl, then the database opened by calling
HISctl with
HISCTLS_PATH.
The
HISclose function closes the handle
history and deallocates
any resources associated with it. It returns
false on failure or
true on success.
The
HISsync function synchronises any outstanding transactions associated
with
history to disk.
HISsetcache associates a cache used for speeding up HIScheck with
history. The cache will occupy approximately
size bytes.
HISlookup retrieves a token from
history based on the passed
key (normally the Message-ID). If no entry with an associated token can
be found,
HISlookup will return
false. If a token is found
arrived,
expires, and
posted are filled in with the
message arrival, expiry, and posting times respectively (or zero, if the time
component is not available), in addition to
token being set to the
retrieved token and a function return value of
true. Any of arrived,
expires, posted, or token may be
NULL in which case that component is
not returned to the caller, without affecting the return value.
HIScheck checks the database
history for
key (normally the
Message-ID); if
key has previously been set via
HISwrite,
HIScheck returns
true, else
false.
HISwrite writes a new entry to the database
history associated
with
key.
arrived,
posted, and
expired specify the
arrival, posting, and expiry time respectively;
posted and
expired may be specifed as <= 0 in which case that component shall
be treated as absent in the database.
token is associated with the
specified
key.
HISwrite returns
true on success, or
false on failure. The behaviour when
key is not unique with
respect to the existing entries in
history is unspecified.
HISremember writes a new entry to the database
history associated
with
key, merely remembering that this
key has been seen,
together with its arrival time
arrived and also its posting time
posted, if known. (Otherwise, its posting time may be specified as
<= 0 in case it is absent.)
HISremember returns
true on
success, or
false on failure. The behaviour when
key is not
unique with respect to the existing entries in
history is unspecified.
HISreplace replaces an existing entry in the database
history,
associated with
key.
arrived,
posted,
expired
specify the arrival, posting and expiry time respectively;
posted and
expired may be specifed as <= 0 in which case that component shall
be treated as absent in the database.
token is associated with the
specified
key; if
NULL then the history database merely
remembers that this
key has been seen, together with its arrival time.
HISreplace returns
true on success, or
false on failure.
HISexpire expires the history database associated with
history,
creating a new, replacement, database in the same location if
path is
NULL, or in
path if not
NULL; if
path is not
NULL then the replacement of the old history database with the new one
is assumed to be performed out of band by the caller. The
writing flag
is normally passed as
true, if you wish to inhibit writing of the new
database (and so merely see the callbacks),
writing may be set
false.
If the underlying history mechanism needs to pause the server, the
reason
string is used as the argument to the `ctlinnd pause' command, and as such the
server should be reserved by the caller prior to calling
HISexpire; if
the caller wishes to inhibit pausing of the server, passing
NULL will
achieve this. If
reason is not
NULL, then on successful return
from
HISexpire the server will be left paused and the caller should
unpause it.
The history database is scanned and entries with an associated storage token are
passed to the discrimination function
exists.
If
exists() returns
false it indicates that stored entity
associated with token is no longer available (or no longer required), and
therefore the associated history entry may be expired once it meets the
threshold constraint. If
exists() returns
true the entry
is kept as-is in the newly expired history database.
The
exists function is passed the arrival, posting and expiry times, in
addition to the token associated with the entry. Note that posting and/or
expiry may be zero, but that the token will never be
NULL (such entries
are handled solely via the threshold mechanism). The storage token passed to
the discrimination function may be updated if required (for example, as might
be needed by a hierachical storage management implementation).
Entries in the database with a posting time less than
threshold with no
token associated with them are deleted from the database. In case the posting
time is unknown, the arrival time is used instead.
The parameter
cookie is passed to the discrimination function, and may be
used for any purpose required by the caller.
If the discrimination function attempts to access the underlying database (for
read or write) during the callback, the behaviour is unspecified.
HISwalk provides an iteration function for the specified
history
database. For every entry in the history database,
callback is invoked,
passing the
cookie, arrival, posting, and expiry times, in addition to
the token associated with the entry. If the
callback() returns
false the iteration is aborted and
HISwalk returns
false
to the caller.
To process the entire database in the presence of a running server,
reason may be passed; if this argument is not
NULL, it is used
as an an argument to the `ctlinnd (reserve|pause|go)' commands. If
reason is
NULL and the server is running, the behaviour of
HISwalk is undefined.
If the callback function attempts to access the underlying database during the
callback, the behaviour is unspecified.
HISstats returns statistics on the history cache mechanism; given a
handle
history, the return value is a
struct histstats
detailing:
- "hitpos"
- The number of times an item was found directly in the cache and known to
exist in the underlying history manager.
- "hitneg"
- The number of times an item was found directly in the cache and known not
to exist in the underlying history manager.
- "misses"
- The number of times an item was not found directly in the cache, but on
retrieval from the underlying history manager was found to exist.
- "dne"
- The number of times an item was not found directly in the cache, but on
retrieval from the underlying history manager was found not to exist.
Note that the history cache is only checked by
HIScheck and only affected
by
HIScheck,
HISwrite,
HISremember and
HISreplace.
Following a call to
HISstats the history statistics associated with
history are cleared.
HISerror returns a string describing the most recent error associated
with
history; the format and content of these strings is history
manager dependent. Note that on setting an error, the history API will call
the
warn function from
libinn(3).
HISctl provides a control interface to the underlying history manager.
The
request argument determines the type of the request and the meaning
of the
val argument. The values for
request are:
- "HISCTLG_PATH" (const char **)
- Get the base file path which the history handle represents. val
should be a pointer to a location of type const char *. The result
must not later be passed to free(3).
- "HISCTLS_PATH" (const char *)
- Set the base file path which this history handle should use; typically
this is used after an anonymous handle has been created using
HISopen(NULL, ...). val should be a value of type const
char * and will be copied before being stored internally.
- "HISCTLS_SYNCCOUNT" (size_t *)
- Set an upper bound on how many history operations may be pending in core
before being synced to permanent storage; 0 indicates unlimited.
val should be a pointer to a value of type size_t and will
not be modified by the call.
- "HISCTLS_NPAIRS" (size_t *)
- Set a hint to the to the underlying history manager as to how many entries
there are expected to be in the history database; 0 indicates that
an automatic or default sizing should be made. val should be a
pointer to a value of type size_t and will not be modified by the
call.
- "HISCTLS_IGNOREOLD" (bool *)
- Instruct the underlying history manager to ignore existing database when
creating new ones; typically this option may be set to true if the
administrator believes that the existing history database is corrupt and
that ignoring it may help. val should be a pointer to a value of
type bool and will not be modified by the call.
- "HISCTLS_STATINTERVAL" (time_t *)
- For the history v6 and tagged hash managers, set the interval, in seconds,
between stat(2)s of the history files checking for replaced files
(as happens during expire); this option is typically used by
nnrpd(8) like applications. val should be a pointer to a
value of type time_t and will not be modified by the call.
HISTORY¶
Written by Alex Kiernan <alexk@demon.net> for InterNetNews 2.4.0.
$Id: libinnhist.pod 9074 2010-05-31 19:01:32Z iulius $