chiark / gitweb /
debugging for thing that crashed
[innduct.git] / storage / tradindexed / tdx-structure.h
1 /*  $Id: tdx-structure.h 5327 2002-03-16 00:33:55Z rra $
2 **
3 **  Data structures for the tradindexed overview method.
4 **
5 **  This header defines the data structures used by the tradindexed overview
6 **  method.  Currently, these data structures are read and written directly to
7 **  disk (and the disk files are therefore endian-dependent and possibly
8 **  architecture-dependent due to structure padding).  This will eventually be
9 **  fixed.
10 **
11 **  The structure of a tradindexed overview spool is as follows:  At the root
12 **  of the spool is a group.index file composed of a struct group_header
13 **  followed by some number of struct group_entry's, one for each group plus
14 **  possibly some number of free entries linked to a free list that's headed
15 **  in the struct index_header.  Each entry corresponds to a particular
16 **  newsgroup carried by the server and stores the high and low article
17 **  numbers for that group, its status flag, and the base of the index file
18 **  for each group.
19 **
20 **  The storage of the group.index file implements a hash table with chaining;
21 **  in other words, there is a table indexed by hash value stored in the
22 **  header that points to the starts of the chains, new entries are appended
23 **  to the end of the file and added to the hash table, and if they collide
24 **  with an existing entry are instead linked to the appropriate hash chain.
25 **
26 **  The overview information for each group is stored in a pair of files named
27 **  <group>.IDX and <group>.DAT.  These files are found in a subdirectory
28 **  formed by taking the first letter of component of the newsgroup name as
29 **  a directory name; in other words, news.announce.newgroups overview data is
30 **  stored in <pathoverview>/n/a/n/news.announce.newgroups.{IDX,DAT}.  The
31 **  .DAT file contains the individual overview entries, one per line, stored
32 **  in wire format (in other words, suitable for dumping directly across the
33 **  network to a client in response to an XOVER command).  The overview data
34 **  stored in that file may be out of order.
35 **
36 **  The .IDX file consists of a series of struct index_entry's, one for each
37 **  overview entry stored in the .DAT file.  Each index entry stores the
38 **  offset of the data for one article in the .DAT file and its length, along
39 **  with some additional metainformation about the article used to drive
40 **  article expiration.  The .IDX file is addressed like an array; the first
41 **  entry corresponds to the article with the number stored in the base field
42 **  of the group_entry for that newsgroup in the group.index file and each
43 **  entry stores the data for the next consecutive article.  Index entries may
44 **  be tagged as deleted if that article has been deleted or expired.
45 */
46
47 #ifndef INN_TDX_STRUCTURE_H
48 #define INN_TDX_STRUCTURE_H 1
49
50 #include "config.h"
51 #include <sys/types.h>
52
53 #include "libinn.h"
54 #include "storage.h"
55
56 /* A location in group.index (this many records past the end of the header of
57    the file).  There's no reason for this to be a struct, but that can't be
58    changed until the format of the group.index file is changed to be
59    architecture-independent since putting it into a struct may have changed
60    the alignment or padding on some architectures. */
61 struct loc {
62     int recno;
63 };
64
65 /* The hard-coded constant size of the hash table for group.index.  This need
66    not be a power of two and has no special constraints.  Changing this at
67    present will break backward compatibility with group.index files written by
68    previous versions of the code. */
69 #define TDX_HASH_SIZE   (16 * 1024)
70
71 /* A magic number for the group.index file so that we can later change the
72    format in a backward-compatible fashion. */
73 #define TDX_MAGIC       (~(0xf1f0f33d))
74
75 /* The header at the top of group.index.  magic contains GROUPHEADERMAGIC
76    always; hash contains pointers to the heads of the entry chains, and
77    freelist points to a linked list of free entries (entries that were used
78    for groups that have since been deleted). */
79 struct group_header {
80     int         magic;
81     struct loc  hash[TDX_HASH_SIZE];
82     struct loc  freelist;
83 };
84
85 /* An entry for a particular group.  Note that a good bit of active file
86    information is duplicated here, and depending on the portion of INN asking
87    questions, sometimes the main active file is canonical and sometimes the
88    overview data is canonical.  This needs to be rethought at some point.
89
90    Groups are matched based on the MD5 hash of their name.  This may prove
91    inadequate in the future.  Ideally, INN really needs to assign unique
92    numbers to each group, which could then be used here as well as in
93    tradspool rather than having to do hacks like using a hash of the group
94    name or constructing one's own number to name mapping like tradspool does.
95    Unfortunately, this ideally requires a non-backward-compatible change to
96    the active file format.
97
98    Several of these elements aren't used.  This structure, like the others,
99    cannot be changed until the whole format of the group.index file is changed
100    since it's currently read as binary structs directly from disk. */
101 struct group_entry {
102     HASH        hash;           /* MD5 hash of the group name. */
103     HASH        alias;          /* Intended to point to the group this group
104                                    is an alias for.  Not currently used. */
105     ARTNUM      high;           /* High article number in the group. */
106     ARTNUM      low;            /* Low article number in the group. */
107     ARTNUM      base;           /* Article number of the first entry in the
108                                    .IDX index file for the group. */
109     int         count;          /* Number of articles in group. */
110     int         flag;           /* Posting/moderation status. */
111     time_t      deleted;        /* When this group was deleted, or 0 if the
112                                    group is still valid. */    
113     ino_t       indexinode;     /* The inode of the index file for the group,
114                                    used to detect when the file has been
115                                    recreated and swapped out. */
116     struct loc  next;           /* Next block in this chain. */
117 };
118
119 /* An entry in the per-group .IDX index file. */
120 struct index_entry {
121     off_t       offset;
122     int         length;
123     time_t      arrived;
124     time_t      expires;        /* Expiration time from Expires: header. */
125     TOKEN       token;
126 };
127
128 #endif /* INN_TDX_STRUCTURE_H */