Added some documentation to the uis

Author: edomora97

cpp/server/main.cpp

@@ -43,7 +43,7 @@ kj::MainFunc Main::getMain() {
                         "Port to listen on")
       .addOptionWithArg(
           {'c', "cache-size"}, util::setUint(&Flags::cache_size), "<SZ>",
-          "Maximum size of the cache, in megabytes. 0 means unlimited")
+          "Maximum size of the cache, in MiB. 0 means unlimited")
       .callAfterParsing(KJ_BIND_METHOD(*this, Run))
       .build();
 }

cpp/worker/main.cpp

@@ -2,14 +2,12 @@
 #include <capnp/ez-rpc.h>
 #include <thread>
 
-#include "capnp/server.capnp.h"
 #include "util/daemon.hpp"
 #include "util/flags.hpp"
 #include "util/log_manager.hpp"
 #include "util/misc.hpp"
 #include "util/version.hpp"
 #include "worker/executor.hpp"
-#include "worker/manager.hpp"
 
 const size_t EXP_BACKOFF_MIN = 1;
 const size_t EXP_BACKOFF_MAX = 60000;
@@ -86,7 +84,7 @@ kj::MainFunc Main::getMain() {
                         "Maximum number of pending requests")
       .addOptionWithArg(
           {'c', "cache-size"}, util::setUint(&Flags::cache_size), "<SZ>",
-          "Maximum size of the cache, in megabytes. 0 means unlimited")
+          "Maximum size of the cache, in MiB. 0 means unlimited")
       .callAfterParsing(KJ_BIND_METHOD(*this, Run))
       .build();
 }

python/config.py

@@ -1,9 +1,8 @@
 #!/usr/bin/env python3
 import os
-from typing import List, Optional
 import pytoml
-
 from task_maker.args import CacheMode, UIS, TaskFormat, Arch
+from typing import List, Optional
 
 
 class Config:
@@ -55,7 +54,7 @@ def __init__(self):
         self.run_worker = False
         self.storedir = "~/.cache/task-maker/files"
         self.tempdir = "~/.cache/task-maker/temp"
-        self.cache_size = 128
+        self.cache_size = 2048  # in MiB
         self._get_host_port()
         self._resolve_dir()
 

python/manager.py

@@ -1,9 +1,9 @@
 #!/usr/bin/env python3
 
-import os.path
-import subprocess
 import time
 
+import os.path
+import subprocess
 from task_maker.config import Config
 from task_maker.task_maker_frontend import Frontend
 from typing import List
@@ -69,6 +69,8 @@ def spawn_worker(config: Config):
         args += ["--keep_sandboxes"]
     if config.worker_name is not None:
         args += ["--name", config.worker_name]
+    if config.worker_num_cores is not None:
+        args += ["--num-cores", str(config.worker_num_cores)]
     if config.worker_port is not None:
         args += ["--port", str(config.worker_port)]
     if config.worker_address is not None:

python/uis/__init__.py

@@ -1,29 +1,39 @@
 #!/usr/bin/env python3
+import time
+
 import curses
 import signal
 import threading
-import time
 import traceback
 from abc import ABC, abstractmethod
 from contextlib import contextmanager
 from enum import Enum
-from typing import Dict, List, Optional
-
 from task_maker.config import Config
 from task_maker.formats import Task
 from task_maker.printer import StdoutPrinter, Printer, CursesPrinter
 from task_maker.source_file import SourceFile
 from task_maker.task_maker_frontend import Result, ResultStatus, Resources
+from typing import Dict, List, Optional
 
 
 class SourceFileCompilationStatus(Enum):
+    """
+    Status of the compilation of a source file
+    - WAITING: the compilation has not started yet
+    - COMPILING: the compilation has started
+    - DONE: the compilation has successfully completed
+    - FAILURE: the compilation failed
+    """
     WAITING = 0
     COMPILING = 1
     DONE = 2
     FAILURE = 3
 
 
 class SourceFileCompilationResult:
+    """
+    Result information about a compilation of a source file
+    """
     def __init__(self, need_compilation):
         self.need_compilation = need_compilation
         self.status = SourceFileCompilationStatus.WAITING
@@ -32,11 +42,23 @@ def __init__(self, need_compilation):
 
 
 class UIInterface:
+    """
+    This class is the binding between the frontend and the task format and the
+    UIs. The format will register the solutions, the frontend will call its
+    callbacks and the state is stored in this class (and in it's subclasses).
+    The UI will use the data inside this.
+    """
     def __init__(self, task: Task, do_print: bool):
+        """
+        :param task: The task this UIInterface is bound to
+        :param do_print: Whether the logs should be printed to stdout (print
+        interface)
+        """
         self.task = task
         self.non_solutions = dict(
         )  # type: Dict[str, SourceFileCompilationResult]
         self.solutions = dict()  # type: Dict[str, SourceFileCompilationResult]
+        # all the running tasks: (name, monotonic timestamp of start)
         self.running = dict()  # type: Dict[str, float]
         self.warnings = list()  # type: List[str]
         self.errors = list()  # type: List[str]
@@ -47,11 +69,16 @@ def __init__(self, task: Task, do_print: bool):
             self.printer = Printer()
 
     def add_non_solution(self, source_file: SourceFile):
+        """
+        Add a non-solution file to the ui (ie a generator/checker/...)
+        """
         name = source_file.name
         log_prefix = "Compilation of non-solution {} ".format(name).ljust(50)
         self.non_solutions[name] = SourceFileCompilationResult(
             source_file.language.need_compilation)
         self.printer.text(log_prefix + "WAITING\n")
+
+        # TODO: at some point extract those functionality into some wrapper
         if source_file.language.need_compilation:
 
             def notifyStartCompiltion():
@@ -88,6 +115,9 @@ def getStderr(stderr):
             self.non_solutions[name].status = SourceFileCompilationStatus.DONE
 
     def add_solution(self, source_file: SourceFile):
+        """
+        Add a solution to the UI
+        """
         name = source_file.name
         log_prefix = "Compilation of solution {} ".format(name).ljust(50)
         self.solutions[name] = SourceFileCompilationResult(
@@ -130,18 +160,30 @@ def getStderr(stderr):
             self.solutions[name].status = SourceFileCompilationStatus.DONE
 
     def add_warning(self, message: str):
+        """
+        Add a warning message to the list of warnings
+        """
         self.warnings.append(message)
         self.printer.yellow("WARNING  ", bold=True)
         self.printer.text(message.strip() + "\n")
 
     def add_error(self, message: str):
+        """
+        Add an error message to the list of errors, this wont stop anything
+        """
         self.errors.append(message)
         self.printer.red("ERROR  ", bold=True)
         self.printer.text(message.strip() + "\n")
 
     @contextmanager
     def run_in_ui(self, curses_ui: Optional["CursesUI"],
                   finish_ui: Optional["FinishUI"]):
+        """
+        Wrap a block in the UI's setup/teardown. A curses UI should be stopped
+        before the program exists otherwise the terminal is messed up. This
+        wrapper will start the UIs, yield and stop them after. At the end it
+        will print with the finish ui
+        """
         if curses_ui:
             curses_ui.start()
         try:
@@ -159,6 +201,11 @@ def run_in_ui(self, curses_ui: Optional["CursesUI"],
 
 
 class FinishUI(ABC):
+    """
+    UI used to print the summary of the execution
+    """
+    # if the time / memory usage is greater of the limit * LIMITS_MARGIN that
+    # time/memory is highlighted
     LIMITS_MARGIN = 0.8
 
     def __init__(self, config: Config, interface: Optional[UIInterface]):
@@ -168,13 +215,22 @@ def __init__(self, config: Config, interface: Optional[UIInterface]):
 
     @abstractmethod
     def print(self):
+        """
+        Print the entire result summary
+        """
         pass
 
     @abstractmethod
     def print_summary(self):
+        """
+        Print only the summary grid with the overview of the results
+        """
         pass
 
     def print_final_messages(self):
+        """
+        Print the warning and error messages
+        """
         if not self.interface:
             return
         if sorted(self.interface.warnings):
@@ -267,34 +323,47 @@ def _print_exec_stat(self, time, memory, time_limit, memory_limit, name):
 
 
 class CursesUI(ABC):
+    """
+    Running interface using the curses library to look nice in the terminal
+    """
+    # limit the frame rate
     FPS = 30
 
     def __init__(self, config: Config, interface: UIInterface):
         self.config = config
         self.interface = interface
+        # the ui runs in a different thread
         self.thread = threading.Thread(
             target=curses.wrapper, args=(self._wrapper, ))
         self.stopped = False
         self.errored = False
 
     def start(self):
+        """
+        Start the UI starting the thread and messing up the terminal
+        """
         self.stopped = False
         self.thread.start()
 
     def stop(self):
+        """
+        Stops the thread and wait for it's termination. This will fix the
+        terminal closing curses
+        """
         self.stopped = True
         self.thread.join()
 
     def _wrapper(self, stdscr):
         try:
             curses.start_color()
             curses.use_default_colors()
-            for i in range(1, curses.COLORS):
-                curses.init_pair(i, i, -1)
+            if hasattr(curses, "COLORS"):
+                for i in range(1, curses.COLORS):
+                    curses.init_pair(i, i, -1)
             curses.halfdelay(1)
             pad = curses.newpad(10000, 1000)
             printer = CursesPrinter(pad)
-            loading_chars = "-\\|/"
+            loading_chars = r"◐◓◑◒"
             cur_loading_char = 0
             pos_x, pos_y = 0, 0
             while not self.stopped:
@@ -333,6 +402,10 @@ def _wrapper(self, stdscr):
 
     @abstractmethod
     def _loop(self, printer: CursesPrinter, loading: str):
+        """
+        The UI should inherit from this class and implement this method to print
+        to the screen
+        """
         pass
 
     def _print_running_tasks(self, printer: CursesPrinter):

python/uis/bulk_finish_ui.py

@@ -1,29 +1,37 @@
 #!/usr/bin/env python3
-from typing import List
 import shutil
-
-from task_maker.printer import StdoutPrinter
 from task_maker.config import Config
+from task_maker.printer import StdoutPrinter
 from task_maker.uis import FinishUI, UIInterface
 from task_maker.uis.ioi import IOIUIInterface
 from task_maker.uis.ioi_finish_ui import IOIFinishUI
 from task_maker.uis.terry import TerryUIInterface
 from task_maker.uis.terry_finish_ui import TerryFinishUI
+from typing import List
 
 
 def _horizontal_line():
+    """
+    Print an horizontal line in the center of the screen
+    """
     size = shutil.get_terminal_size((80, 20))
     print("\u2014" * size.columns)
 
 
 class BulkFinishUI(FinishUI):
+    """
+    Finish UI for bulk makes, this will take many UIInterfaces
+    """
     def __init__(self, config: Config):
         super().__init__(config, None)
         self.interfaces = list()  # type: List[UIInterface]
         self.uis = list()  # type: List[FinishUI]
         self.errors = list()  # type: List[str]
 
     def add_interface(self, interface: UIInterface):
+        """
+        Add a new interface to track and later print the final result
+        """
         if isinstance(interface, IOIUIInterface):
             ui = IOIFinishUI(self.config, interface)
         elif isinstance(interface, TerryUIInterface):
@@ -35,9 +43,15 @@ def add_interface(self, interface: UIInterface):
         self.uis.append(ui)
 
     def add_error(self, message: str):
+        """
+        Add an error to the errors list
+        """
         self.errors.append(message)
 
     def print(self):
+        """
+        Print the final result of all the interfaces
+        """
         for ui in self.uis:
             _horizontal_line()
             ui.print()
@@ -46,6 +60,9 @@ def print(self):
         self.print_final_messages()
 
     def print_summary(self):
+        """
+        Print the summary of the executions of each task close together
+        """
         printer = StdoutPrinter()
         printer.blue("Bulk summary:\n", bold=True)
         for i, ui in enumerate(self.uis):
@@ -57,6 +74,9 @@ def print_summary(self):
             ui.print_final_messages()
 
     def print_final_messages(self):
+        """
+        Print the list of bulk errors
+        """
         if self.errors:
             printer = StdoutPrinter()
             print()