"Fossies" - the Fresh Open Source Software Archive

Member "tin-2.4.1/doc/internals.txt" (28 Aug 2013, 3803 Bytes) of package /linux/misc/tin-2.4.1.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 I/O in tin (updated 05/01/98)
    2 ----------
    3 
    4 All critical I/O, be it NNTP data or not, should be done with
    5 tin_fgets() This handles data formatting, removes any trailing \n and \r
    6 and deals with timeouts, reconnections and user aborts.
    7 It always returns a full line of data - all memory management is handled
    8 internally.
    9 
   10 It supports the use of 'q' to abort the operation and 'Q' to exit tin
   11 without error recovery.
   12 
   13 tin_errno will be set to !0 to flag errors. Currently the only
   14 supported error is 'user aborted with q'.
   15 
   16 Closing data streams should be done with TIN_FCLOSE(fp) as the NNTP
   17 socket should be kept open, whereas local spool fd's must be closed.
   18 TIN_FCLOSE() takes care of this.
   19 
   20 If you wish to quit reading a NNTP stream, then call drain_buffer(fp) to
   21 clear out any pending data on the NNTP socket.
   22 
   23 nntp_command(command, valid_response, rest_of_data) should be used for
   24 sending all generic NNTP command. It returns a fd to the open stream
   25 for reading the rest of the data.
   26 
   27 
   28 Example of a typical exchange:
   29 
   30 if ((fp = nntp_command ("GROUP comp.thing", OK_GROUP, NULL)) != NULL) {
   31 
   32 	while ((ptr = tin_fgets(fp, FALSE)) != NULL)
   33 		process_data(ptr);
   34 
   35 #ifdef NNTP_ABLE
   36 	if (ptr)
   37 		drain_buffer(fp);
   38 #endif /* NNTP_ABLE */
   39 
   40 	TIN_FCLOSE(fp);
   41 
   42 	if (tin_errno)
   43 		handle_abort();
   44 }
   45 
   46 
   47 
   48 Hashing in tin (updated 05/01/98)
   49 --------------
   50 
   51 All the main arrays in tin are dynamically managed by functions in memory.c
   52 They are preallocated to an initial size and then grown if the high
   53 water mark is exceeded.
   54 
   55 The main structures are:
   56 
   57 active[]
   58 An array of all the groups in the active file
   59 
   60 arts[]
   61 This is an array of the article headers for the current group. Only headers
   62 present in the overview (NOV) database are stored.
   63 
   64 base[]
   65 An array of integers that represent the index in arts[] of the current
   66 root article for each displayed thread.
   67 
   68 group_hash[]
   69 active[] is hashed for faster access. An entry of -1 denotes no group at
   70 this hashnode, >= 0 denotes an index into active[]
   71 Multiple groups on one node are chained via the .next field (another index
   72 ptr to active[])
   73 
   74 my_group[]
   75 List of integer pointers into active[]
   76 These are the groups that actually appear on the selection screen
   77 
   78 msgids[]
   79 Hashed array of all the individual message-ids in arts[]
   80 All the Message-ID and Reference headers are broken down and stored here.
   81 They are linked together by parent, sibling and child pointers
   82 
   83 table[]
   84 Hash of the key text headers from the articles, to save space and speed up
   85 searches and compares.
   86 
   87 
   88 The functions that manipulate the above include:
   89 
   90 active.c:
   91 	read_news_active_file() populates active[] using group_add()
   92 
   93 art.c:
   94 	Many of the overview headers are stored with hash_str()
   95 	base[] is populated by find_base()
   96 
   97 hashstr.c:
   98 	hash_str() Hashes text strings
   99 	In the article header, the following text is hashed:
  100 		From: (including full name if supplied)
  101 		Archive-name:
  102 		Subject:
  103 
  104 list.c:
  105 	init_group_hash() clears group_hash[]
  106 	find_group_index() returns index of group in active[]
  107 	group_find() returns a pointer to a group in active[]
  108 	group_add() adds a group into active[] and hashes it in group_hash[]
  109 	hash_groupname() returns hash key for a group
  110 		This is also used to hash the actual filenames written
  111 		in ~/.tin/.news (when not using NNTP)
  112 		There is experimental code here for a (presumably)
  113 		improved hash function that was never completed.
  114 
  115 main.c:
  116 	Just the initializers for hashing
  117 
  118 memory.c:
  119 	Dynamic array management.
  120 	hash_reclaim() - free up table[] which holds the
  121 	text cache
  122 
  123 refs.c:
  124 	Handling for msgids[]
  125 	When threading, each msgid in the hash has a pointer back to
  126 	its article header in arts[] or ART_UNAVAILABLE if the article is not
  127 	available
  128 
  129 select.c:
  130 	my_group_add() adds a group to my_group[]
  131 	my_group_find() returns the index of a group in my_group[]