Ticket #145: reading.texi.patch

gnugo/doc/reading.texi

@@ -225 +225 @@
 option @pxref{Invoking GNU Go}.
 
 The hash table is created once and for all at the beginning of
-the game by the function @code{hashtable_new()}. Although hash
+the game by the function @code{reading_cache_init()}. Although hash
 memory is thus allocated only once in the game, the table is
 reinitialized at the beginning of each move by a call to
-@code{hashtable_clear()} from @code{genmove()}.
+@code{reading_cache_clear()} from @code{genmove()}.
 
 @menu
 * Hash Calculation::            Calculation of the hash value
 * Hash Organization::           Organization of the hash table
-* Hash Structures::             Structures in @file{hash.h}
 @end menu
 
 @node Hash Calculation
@@ -249 +248 @@
 @enumerate
 @item First we define a @dfn{go position}.  This positions consists of
 @itemize @bullet
-@item the actual board, i.e. the locations and colors of the stones
-@item A @dfn{ko point}, if a ko is going on.  The ko point is defined as
+@item the actual board, i.e. the locations and colors of the stones;
+@item a @dfn{ko point}, if a ko is going on; the ko point is defined as
 the empty point where the last single stone was situated before
 it was captured.
 @end itemize
 
+In addition to that we include some more information into the hash code,
+that describes stored analisys results:
+@itemize @bullet
+@item a @dfn{komaster} and @dfn{kom_pos}, @xref{Ko},
+@item an ID (an int between 0 and 255) of a function used to calculate
+the results;
+@item a target of analisys (up to two positions on a board);
+@item sometimes some extra information used by various functions.
+@end itemize
+
 It is not necessary to specify the color to move (white or black)
 as part of the position. The reason for this is that read results
 are stored separately for the various reading functions such as
 @code{attack3}, and it is implicit in the calling function which
 player is to move.
 
-@item For each location on the board we generate random numbers:
-@itemize @bullet
-@item A number which is used if there is a white stone on this location
-@item A number which is used if there is a black stone on this location
-@item A number which is used if there is a ko on this location
-@end itemize
-
+@item For each of the above information (excluding extra information)
+we generate tables with random numbers for each: function, komaster
+status or position on a board.
 These random numbers are generated once at initialization time and
 then used throughout the life time of the hash table.
 
 @item The hash key for a position is the XOR of all the random numbers
-which are applicable for the position (white stones, black stones, and
-ko position).
+which are applicable for the position. If extra information is needed
+it is passed by a function as a hash code which is XORed into the
+resulting hash key.
 @end enumerate
 
 @node Hash Organization
 @subsection Organization of the hash table
 
-The hash table consists of 3 parts:
-
-@cindex Hash node
-@cindex Read result
-
-@itemize @bullet
-@item An area which contains so called @dfn{Hash Nodes}. Each hash node
-contains:
-@itemize @minus
-@item A go position as defined above.
-@item A computed hash value for the position
-@item A pointer to Read Results (see below)
-@item A pointer to another hash node.
-@end itemize
-
-@item An area with so called Read Results.  These are used to store
-which function was called in the go position, which string was
-under attack or to be defended, and the result of the reading.
-
-Each Read Result contains: 
-@itemize @minus
-@item the function ID (an int between 0 and 255), the position of the
-string under attack and a depth value, which is used to
-determine how deep the search was when it was made, packed into
-one 32 bit integer. 
-@item The result of the search (a numeric value) and a position to
-play to get the result packed into one 32 bit integer. 
-@item A pointer to another Read Result.
-@end itemize
-
-@item An array of pointers to hash nodes.  This is the hash table
-proper.
-
-@end itemize
-
-When the hash table is created, these 3 areas are allocated using
-@code{malloc()}.  When the hash table is populated, all contents are taken
-from the Hash nodes and the Read results. No further allocation is
-done and when all nodes or results are used, the hash table is full.
-Nothing is deleted from the hash table except when it is totally
-emptied, at which point it can be used again as if newly initialized.
-
-@findex hashtable_search
-When a function wants to use the hash table, it looks up the current
-position using @code{hashtable_search()}. If the position doesn't already
-exist there, it can be entered using
-
-@findex hashtable_enter_position
-@code{hashtable_enter_position()}.  
-
-@findex hashtable_enter_position
-Once the function has a pointer to the hash node containing a
-function, it can search for a result of a previous search using
-@code{hashnode_search()}.  If a result is found, it can be used, and
-if not, a new result can be entered after a search using 
-@findex hashnode_new_result
-@code{hashnode_new_result()}.
-
-Hash nodes which hash to the same position in the hash table
-(collisions) form a simple linked list.  Read results for the same
-position, created by different functions and different attacked or
-defended strings also form a linked list.
-
-This is deemed sufficiently efficient for now, but the representation
-of collisions could be changed in the future.  It is also not
-determined what the optimum sizes for the hash table, the number of
-positions and the number of results are.
-
-@node Hash Structures
-@subsection Hash Structures
-
 The basic hash structures are declared in @file{engine/hash.h} and
-@file{engine/cache.c}
-
-@example
-typedef struct hashposition_t @{
-  Compacttype  board[COMPACT_BOARD_SIZE];
-  int          ko_pos;
-@} Hashposition;
-@end example
+@file{engine/cache.h}
 
-Represents the board and optionally the location of a ko,
-which is an illegal move. The player whose move is next
-is not recorded.
+The hash table consists of an array of pointers to hash entries and
+variable that defines number of the entries.
 
 @example
 typedef struct @{
-  Hashvalue     hashval;
-  Hashposition  hashpos;
-@} Hash_data;
-@end example
-
-Represents the return value of a function (@code{hashval}) and
-the board state (@code{hashpos}).
-
-@example
-typedef struct read_result_t @{
-  unsigned int data1;   
-  unsigned int data2;
+  unsigned int num_entries;
+  Hashentry *entries;
+@} Transposition_table;
 
-  struct read_result_t *next;
-@} Read_result;
+Transposition_table ttable;
 @end example
 
-The data1 field packs into 32 bits the following fields:
+@cindex Hash entry
 
-@example
-
-komaster:  2 bits (EMPTY, BLACK, WHITE, or GRAY)
-kom_pos : 10 bits (allows MAX_BOARD up to 31)
-routine :  4 bits (currently 10 different choices)
-str1    : 10 bits
-stackp  :  5 bits
-
-@end example
-
-The data2 field packs into 32 bits the following fields:
+The @dfn{Hash Entry} consists of two @dfn{Hash Nodes}. One is the
+most reliable node and the second is the newest. The reliability is
+computed based on cost of the function, which created a node and
+depth of analysis for that node (the lower depth the more reliable
+results).
 
 @example
-
-status :   2 bits (0 free, 1 open, 2 closed)
-result1:   4 bits
-result2:   4 bits
-move   :  10 bits
-str2   :  10 bits
-
+typedef struct @{
+  Hashnode most_reliable;
+  Hashnode newest;
+@} Hashentry;
 @end example
 
-The @code{komaster} and @code{(kom_pos)} field are
-documented in @xref{Ko}.
+@cindex Hash node
 
-When a new result node is created, 'status' is set to 1 'open'.
-This is then set to 2 'closed' when the result is entered. The main
-use for this is to identify open result nodes when the hashtable is
-partially cleared. Another potential use for this field is to
-identify repeated positions in the reading, in particular local
-double or triple kos.
+Each hash node contains a computed hash value (as defined above)
+and @dfn{Read Results}.
 
 @example
-typedef struct hashnode_t @{
-  Hash_data            key;
-  Read_result        * results;
-  struct hashnode_t  * next;
+typedef struct @{
+  Hash_data key;
+  HASHNODE_DATATYPE data; /* 32-bit value */
 @} Hashnode;
 @end example
 
-The hash table consists of hash nodes.  Each hash node consists of
-The hash value for the position it holds, the position itself and
-the actual information which is purpose of the table from the start.
+@cindex Read result
 
-There is also a pointer to another hash node which is used when
-the nodes are sorted into hash buckets (see below).
+Read Results are used to store which function was called in the go
+position, which string was under attack or to be defended, and the
+result of the reading. The result is packed into one 32 bit integer.
+Each Read Result contains: 
+@itemize @minus
+@item a remaining (to the max depth) depth value, which is used to
+determine how deep the search was when node was stored (5 bits); 
+@item the results of the search (two numeric values - 2 x 4 bits);
+@item a cost of a function which stored the result (an arbitrary
+numeric value) (4 bits);
+@item a move to play to get the result (10 bits).
+@end itemize
 
 @example
-typedef struct hashtable @{
-  size_t         hashtablesize; /* Number of hash buckets */
-  Hashnode    ** hashtable;     /* Pointer to array of hashnode lists */
+#define hn_create_data(remaining_depth, value1, value2, move, cost) \
+    ((((value1)         & 0x0f)  << 23) \
+   | (((value2)         & 0x0f)  << 19) \
+   | (((move)           & 0x3ff) <<  9) \
+   | (((cost)           & 0x0f)  <<  5) \
+   | (((remaining_depth & 0x1f)/*<<  0*/)))
+@end example
 
-  int            num_nodes;     /* Total number of hash nodes */
-  Hashnode     * all_nodes;     /* Pointer to all allocated hash nodes. */
-  int            free_node;     /* Index to next free node. */
+When the hash table is created, the hash entries are allocated using
+@code{malloc()}. After that, no further allocation is
+done and when all nodes or results are used, the hash table is full.
+Nothing is deleted, instead nodes are replaced by newer or more
+reliable nodes (when collision occurs).
 
-  int            num_results;   /* Total number of results */
-  Read_result  * all_results;   /* Pointer to all allocated results. */
-  int            free_result;   /* Index to next free result. */
-@} Hashtable;
-@end example
+@findex tt_get
+When a function wants to use the hash table, it looks up the current
+position using @code{tt_get()}. If the position doesn't already
+exist there, it can be entered using
 
-The hash table consists of three parts:
+@findex tt_update
+@code{tt_update()}.  
 
-@itemize @bullet
-@item The hash table proper: a number of hash buckets with collisions
-being handled by a linked list.
-@item The hash nodes.  These are allocated at creation time and are 
-never removed or reallocated in the current implementation.
-@item The results of the searches.  Since many different searches can
-be done in the same position, there should be more of these than
-hash nodes.
-@end itemize
+@findex tt_update
+There are several macros which store the result and return it from
+a searching functions. They are named @code{READ_RETURN0},
+@code{READ_RETURN}, @code{READ_RETURN_SEMEAI}, @code{READ_RETURN_CONN},
+@code{READ_RETURN_HASH} and @code{READ_RETURN2} and can be found in
+@file{engine/cache.h}.
 
 @node Persistent Cache
 @section Persistent Reading Cache