timeinfo.h

   1 #ifndef ZZGO_TIMEINFO_H
   2 #define ZZGO_TIMEINFO_H
   3
   4 /* Time-keeping information about time to spend on the next move and/or
   5  * rest of the game. This is only a hint, an engine may decide to spend
   6  * more or less time on a given move, provided it never forfeits on time. */
   7
   8 /* Note that some ways of specifying time (TD_GAMES) may not make sense
   9  * with all engines. */
  10
  11 #include <stdbool.h>
  12
  13 #include "board.h"
  14
  15 struct time_info {
  16         /* For how long we can spend the time? */
  17         enum time_period {
  18                 TT_NULL, // No time limit. Other structure elements are undef.
  19                 TT_MOVE, // Time for the next move.
  20                 TT_TOTAL, // Time for the rest of the game. Never seen by engine.
  21         } period;
  22         /* How are we counting the time? */
  23         enum time_dimension {
  24                 TD_GAMES, // Fixed number of simulations to perform.
  25                 TD_WALLTIME, // Wall time to spend performing simulations.
  26         } dim;
  27         /* The actual time count. */
  28         union {
  29                 int games; // TD_GAMES
  30                 struct {   // TD_WALLTIME
  31                         /* Main thinking time. 0 if we are already completely
  32                          * in byoyomi. */
  33                         double main_time;
  34
  35                         /* Byoyomi time. This time must be remembered to avoid
  36                          * rushing at the end of the main period. If no byoyomi,
  37                          * set to 0. Otherwise, both periods and stones are
  38                          * larger than zero, and initially we have _periods
  39                          * periods of length _time and have to play _stones
  40                          * stones in each. If we play in canadian byoyomi,
  41                          * _time will shrink until we play all stones of the
  42                          * current period; _max always keeps period length
  43                          * for reference. */
  44                         /* (In normal time settings, one of _periods or _stones
  45                          * is 1.) */
  46                         double byoyomi_time;
  47                         int byoyomi_periods;
  48                         int byoyomi_stones;
  49                         double byoyomi_time_max;
  50                         int byoyomi_stones_max;
  51                         bool canadian; // time_left field meaning changes
  52
  53                         /* Absolute time at which our timer started for current move,
  54                          * 0 if not yet known. The engine always sees > 0. */
  55                         double timer_start;
  56                 } t;
  57         } len;
  58         /* If true, this time info is independent from GTP time_left updates,
  59          * which will be ignored. This is the case if the time settings were
  60          * forced on the command line. */
  61         bool ignore_gtp;
  62 };
  63
  64 /* Parse time information provided in custom format:
  65  *   =NUM - fixed number of simulations per move
  66  *   NUM - number of seconds to spend per move (can be float)
  67  *   _NUM - number of seconds to spend per game
  68  *
  69  * Returns false on parse error.  */
  70 bool time_parse(struct time_info *ti, char *s);
  71
  72 /* Update time settings according to gtp time_settings command.
  73  * main_time < 0 implies no time limit. */
  74 void time_settings(struct time_info *ti, int main_time, int byoyomi_time, int byoyomi_stones, int byoyomi_periods);
  75
  76 /* Update time information according to gtp time_left command. */
  77 void time_left(struct time_info *ti, int time_left, int stones_left);
  78
  79 /* Start our timer. kgs does this (correctly) on "play" not "genmove"
  80  * unless we are making the first move of the game. */
  81 void time_start_timer(struct time_info *ti);
  82
  83 /* Subtract given amount of elapsed time from time settings. */
  84 void time_sub(struct time_info *ti, double interval, bool new_move);
  85
  86 /* Returns the current time. */
  87 double time_now(void);
  88
  89 /* Sleep for a given interval (in seconds). Return immediately if interval < 0. */
  90 void time_sleep(double interval);
  91
  92
  93 /* Based on existing time information, compute the optimal/maximal time
  94  * to be spent on this move. */
  95 /* The values can be negative, indicating severe time shortage (less time
  96  * available than netlag safety margin) and consequently need to choose
  97  * a move ASAP. */
  98
  99 struct time_stop {
 100         /* spend this amount of time if possible */
 101         union {
 102                 double time; // TD_WALLTIME
 103                 int playouts; // TD_GAMES
 104         } desired;
 105         /* spend no more than this time */
 106         union {
 107                 double time; // TD_WALLTIME
 108                 int playouts; // TD_GAMES
 109         } worst;
 110 };
 111
 112 /* fuseki_end and yose_start are percentages of expected game length. */
 113 void time_stop_conditions(struct time_info *ti, struct board *b, int fuseki_end, int yose_start, struct time_stop *stop);
 114
 115 #endif