hex

commit 0ee5d6cf60fc61fcc344b807a8c1b44291103cfa
parent e15f72b1f7c632b577ffe191b3d0716fb4608631
Author: Mikołaj Lenczewski <mblenczewski@gmail.com>
Date:   Thu,  2 Jan 2025 14:34:50 +0000

Improve tournament-host.py docs

Diffstat:
M
README.txt
 | 
39
++++++++++++++++++++++++++++++++++++---
M
schedule.txt
 | 
5
+++++
M
tournament-host.py
 | 
2
+-

3 files changed, 42 insertions(+), 4 deletions(-)
diff --git a/README.txt b/README.txt
@@ -18,34 +18,63 @@ hex-server: Building
 ------------------------------------------------------------------------------
 To build the server and all agents, run the following shell command in the
 project's root directory:
+
 ```sh
 $ ./build.sh
+$ WERROR=1 ./build.sh # alternatively, to build all binaries with -Werror
 ```
 
 To clean all built artefacts, run the following shell command:
+
 ```sh
 $ ./clean.sh
 ```
+
 Before running the hex-server, or the tournament-host.py helper script, a
 number of hex agent runner users must be added to the system. This is done
 to enable hard limits on the number of threads and memory any given agent is
 able to use (avoiding starving out other agents, or killing the server or
 opponent agent). To install these users, run the following shell command:
+
 ```sh
 $ sudo ./install # this must be ran as root, to be able to add users
 ```
 
 To remove the previously added users, run the followind shell command:
+
 ```sh
-$ sudo ./uninstall
+$ sudo ./uninstall # must be ran as root, to remove added users
 ```
 
 hex-server: Usage
 ------------------------------------------------------------------------------
-The server can be invoked using the following shell command:
+To run a tournament, you can use the included `tournament-host.py` script. Its
+usage is as follows:
+
+```sh
+$ sudo ./tournament-host.py [-hv] <tournament-schedule.txt> <output.log> \
+                 [-d <board-dimensions>] [-s <time-limit-secs>] \
+                 [-t <agent-thread-limit>] [-m <agent-mem-limit-mib>] \
+                 [--concurrent-matches {1,2,3,4,5,6,7,8}]
+```
+
+NOTE: the `output.log` file will be created if it does not exist. Otherwise, it
+will be overwritten
+
+NOTE: the tournament host MUST be ran as root (or by a user with the Linux
+CAP_SETUID capability), due to the hex game server using setuid() to enforce
+process resource limits. The tournament host will by default use all users
+with usernames of the form `hex-agent-$id`, where `$id` is an integer, in a
+round-robin fashion. To generate these users, please run the `install.sh`
+script as root (or via `sudo`).
+
+Alternatively, to run a single game between two agents, the server can be
+directly invoked using the following shell command:
+
 ```sh
 $ sudo ./server/bin/hex-server -a <agent-1> -ua <uid> -b <agent-2> -ub <uid> \
-                 [-d 11] [-s 300] [-t 4] [-m 1024] [-v]
+                 [-d <board-dimensions>] [-s <time-limit-secs>] \
+                 [-t <agent-thread-limit>] [-m <agent-mem-limit-mib>] [-v]
 ```
 
 NOTE: The server MUST be ran as root (i.e. as a privileged process), or by a
@@ -70,6 +99,7 @@ Server Options:
 +-----+-----------------------------------------------+-----------+-----------+
 
 Each agent will be invoked using the following shell command:
+
 ```sh
 <agent-string> <server-host> <server-port>
 ```
@@ -81,6 +111,7 @@ differently named options, or having an interpreted agent and having to pass
 the agent source to the interpreter).
 
 An example of such a wrapper script is as follows:
+
 ```sh
 #!/bin/sh
 
@@ -100,6 +131,7 @@ example of the wrapper scripts used to invoke the agents, please see the
 NOTE: the wrapper script, if used, must be made executable. This can be done
 using the following shell command (replacing `/tmp/my_agent/` with your
 specific agent's directory):
+
 ```sh
 $ chmod +x /tmp/my_agent/my_wrapper_script.sh
 ```
@@ -174,6 +206,7 @@ Protocol Messages:
 +-------+-----------+---------------------------------------------------------+
 
 An example of this protocol defined in a C-like language is as follows:
+
 ```c
 enum player_type : u32 {
   PLAYER_BLACK  = 0,
diff --git a/schedule.txt b/schedule.txt
@@ -1,4 +1,9 @@
 # schedule file consisting of comma-separated agent pairs
+# ============================================================================
+# to edit the below games or add your own, add a line in the following format:
+#   <player-1-command>,<player-2-command>
+#
+# NOTE: lines starting with a '#' are ignored
 
 agents/example_python3_agent/agent.py,agents/example_python3_agent/run.sh
 
diff --git a/tournament-host.py b/tournament-host.py
@@ -14,7 +14,7 @@ import time
 HEX_SERVER_PROGRAM = os.path.abspath('./server/bin/hex-server')
 
 HEX_AGENT_USERS = [
-    ent.pw_name for ent in pwd.getpwall() if re.match('hex-agent-\d+$', ent.pw_name)
+    ent.pw_name for ent in pwd.getpwall() if re.match('hex-agent-[0-9]+$', ent.pw_name)
 ]
 
 if not HEX_AGENT_USERS: