"Fossies" - the Fresh Open Source Software Archive

Member "tin-2.6.2/doc/internals.txt" (3 Nov 2021, 3790 Bytes) of package /linux/misc/tin-2.6.2.tar.xz:

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. See also the last Fossies "Diffs" side-by-side code changes report for "internals.txt": 2.6.0_vs_2.6.1.

    1 I/O in tin (updated 05/01/98)
    2 ----------
    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.
   10 It supports the use of 'q' to cancel the operation and 'Q' to exit tin
   11 without error recovery.
   13 tin_errno will be set to !0 to flag errors. Currently the only
   14 supported error is 'user aborted with q'.
   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.
   20 If you wish to quit reading an NNTP stream, then call drain_buffer(fp) to
   21 clear out any pending data on the NNTP socket.
   23 nntp_command(command, valid_response, rest_of_data) should be used for
   24 sending all generic NNTP command. It returns an fd to the open stream
   25 for reading the rest of the data.
   28 Example of a typical exchange:
   30 if ((fp = nntp_command ("GROUP comp.thing", OK_GROUP, NULL)) != NULL) {
   32 	while ((ptr = tin_fgets(fp, FALSE)) != NULL)
   33 		process_data(ptr);
   35 #ifdef NNTP_ABLE
   36 	if (ptr)
   37 		drain_buffer(fp);
   38 #endif /* NNTP_ABLE */
   40 	TIN_FCLOSE(fp);
   42 	if (tin_errno)
   43 		handle_abort();
   44 }
   48 Hashing in tin (updated 05/01/98)
   49 --------------
   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.
   55 The main structures are:
   57 active[]
   58 An array of all the groups in the active file
   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.
   64 base[]
   65 An array of integers that represent the index in arts[] of the current
   66 root article for each displayed thread.
   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[])
   74 my_group[]
   75 List of integer pointers into active[]
   76 These are the groups that actually appear on the selection screen
   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
   83 table[]
   84 Hash of the key text headers from the articles, to save space and speed up
   85 searches and compares.
   88 The functions that manipulate the above include:
   90 active.c:
   91 	read_news_active_file() populates active[] using group_add()
   93 art.c:
   94 	Many of the overview headers are stored with hash_str()
   95 	base[] is populated by find_base()
   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 		Subject:
  103 list.c:
  104 	init_group_hash() clears group_hash[]
  105 	find_group_index() returns index of group in active[]
  106 	group_find() returns a pointer to a group in active[]
  107 	group_add() adds a group into active[] and hashes it in group_hash[]
  108 	hash_groupname() returns hash key for a group
  109 		This is also used to hash the actual filenames written
  110 		in ~/.tin/.news (when not using NNTP)
  111 		There is experimental code here for a (presumably)
  112 		improved hash function that was never completed.
  114 main.c:
  115 	Just the initializers for hashing
  117 memory.c:
  118 	Dynamic array management.
  119 	hash_reclaim() - free up table[] which holds the
  120 	text cache
  122 refs.c:
  123 	Handling for msgids[]
  124 	When threading, each msgid in the hash has a pointer back to
  125 	its article header in arts[] or ART_UNAVAILABLE if the article is not
  126 	available
  128 select.c:
  129 	my_group_add() adds a group to my_group[]
  130 	my_group_find() returns the index of a group in my_group[]