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         union {
  28                 int games; // TD_GAMES
  29                 struct {   // TD_WALLTIME
  30                         /* Recommended wall time for next move or game (seconds).
  31                          * Does not include net lag. Play asap if 0. */
  32                         double recommended_time;
  33
  34                         /* Maximum wall time for next move or game. Will lose on time
  35                          * if exceeded. Does not include net lag. Play asap if 0. */
  36                         double max_time;
  37
  38                         /* Minimum net lag (seconds) to be reserved by the engine.
  39                          * The engine may use a larger safety margin. */
  40                         double net_lag;
  41
  42                         /* Absolute time at which our timer started for current move,
  43                          * 0 if not yet known. The engine always sees > 0. */
  44                         double timer_start;
  45
  46                         /* --- PRIVATE DATA --- */
  47                         /* Byoyomi time per move (even for TT_TOTAL). This time must
  48                          * be remembered to avoid rushing at the end of the main
  49                          * period. 0 if no byoyomi.  An engine should only consider
  50                          * recommended_time, the generic time control code always sets it to
  51                          * the best option (play on main time or on byoyomi time). */
  52                         double byoyomi_time;
  53                         int byoyomi_periods; /* > 0 only for non-canadian byoyomi */
  54                 } t;
  55         } len;
  56 };
  57
  58 /* Parse time information provided in custom format:
  59  *   =NUM - fixed number of simulations per move
  60  *   NUM - number of seconds to spend per move (can be float)
  61  *   _NUM - number of seconds to spend per game
  62  *
  63  * Returns false on parse error.  */
  64 bool time_parse(struct time_info *ti, char *s);
  65
  66 /* Update time settings according to gtp time_settings command. */
  67 void time_settings(struct time_info *ti, int main_time, int byoyomi_time, int byoyomi_stones, int byoyomi_periods);
  68
  69 /* Update time information according to gtp time_left command. */
  70 void time_left(struct time_info *ti, int time_left, int stones_left);
  71
  72 /* Start our timer. kgs does this (correctly) on "play" not "genmove"
  73  * unless we are making the first move of the game. */
  74 void time_start_timer(struct time_info *ti);
  75
  76 /* Set correct time information before making a move, and
  77  * always make it time per move for the engine. */
  78 void time_prepare_move(struct time_info *ti, struct board *board);
  79
  80 /* Returns true if we are in byoyomi (or should play as if in byo yomi
  81  * because remaining time per move in main time is less than byoyomi time
  82  * per move). */
  83 bool time_in_byoyomi(struct time_info *ti);
  84
  85 /* Returns the current time. */
  86 double time_now(void);
  87
  88 /* Sleep for a given interval (in seconds). Return immediately if interval < 0. */
  89 void time_sleep(double interval);
  90
  91
  92 /* Based on existing time information, compute the optimal/maximal time
  93  * to be spent on this move. */
  94
  95 struct time_stop {
  96         /* stop at that time if possible */
  97         union {
  98                 double time; // TD_WALLTIME
  99                 int playouts; // TD_GAMES
 100         } desired;
 101         /* stop no later than this */
 102         union {
 103                 double time; // TD_WALLTIME
 104                 int playouts; // TD_GAMES
 105         } worst;
 106 };
 107
 108 /* fuseki_end and yose_start are percentages of expected game length. */
 109 void time_stop_conditions(struct time_info *ti, struct board *b, int fuseki_end, int yose_start, struct time_stop *stop);
 110
 111 #endif