hypershell.server


Directly embed the server either as a dedicated ServerThread or using one of the provided high-level functions, serve_from(), serve_file(), or serve_forever().

All of the parameters used below are largely the same in each instance. Configuration files have no impact when using the library; i.e., default values are not overridden by configuration.


Warning

While all parameters have reasonable defaults you should always provide your own cryptographically secure authentication key (named auth in all cases).

See DEFAULT_AUTH.

Functions


serve_from(source: Iterable[str], restart_mode: bool = False, task_cores: int = None, task_memory: int = None, task_timeout: int = None, bundlesize: int = 1, bundlewait: int = 5, in_memory: bool = False, no_confirm: bool = False, poll: int = 30, address: Tuple[str, int] = ('localhost', 50001), auth: str = '<not-secure>', max_retries: int = 0, eager: bool = False, redirect_failures: IO = None, evict_after: int = 600, tls: TLSConfig | None = None) → None[source]

Start server with given task source, run until complete.

Parameters:

  • source (Iterable[str]) – Any iterable of command-line tasks.

  • task_cores (int, optional) – Default number of cores to use for each task (default: none). May be overridden by inline-comment.

  • task_memory (int, optional) – Default memory in bytes to use for each task (default: none). May be overridden by inline-comment.

  • task_timeout (int, optional) – Task-level walltime limit in seconds (default: none).

  • bundlesize (int, optional) – Size of task bundles. See DEFAULT_BUNDLESIZE.

  • bundlewait (int, optional) – Waiting period before forcing task bundle push. See DEFAULT_BUNDLEWAIT.

  • restart_mode (bool, optional) – If source is empty, this option allows for the server to continue with scheduling from the database until complete. Conflicts with in_memory. Default is False.

  • in_memory (bool, optional) – If True, revert to basic in-memory queue.

  • no_confirm (bool, optional) – If True, do not check for client confirmation messages.

  • poll (int, optional) – Polling interval in seconds between database queries if no tasks are available. See DEFAULT_SERVER_POLL.

  • address (tuple, optional) – Bind address for server with port number. See DEFAULT_BIND and DEFAULT_PORT.

  • auth (str, optional) – Server authentication key. See DEFAULT_AUTH.

  • max_retries (int, optional) – Number of allowed task retries. See DEFAULT_ATTEMPTS.

  • eager (bool, optional) – When enabled tasks are retried immediately ahead scheduling new tasks. See DEFAULT_EAGER_MODE.

  • redirect_failures (bool, optional) – Open file descriptor to write failed tasks.

  • evict_after (int, optional) – Period in seconds to wait before evicting clients that miss heartbeats. See DEFAULT_EVICT.

  • tls – (TLSConfig, optional): TLS configuration for queue interface. Clients must connect with compatible configuration. See security documentation for details.

Example

>>> from hypershell.server import serve_from
>>> serve_from(['echo AA', 'echo BB', 'echo CC'], auth='my-secret-key')

See also


serve_file(path: str, task_cores: int | None = None, task_memory: int | None = None, task_timeout: int | None = None, bundlesize: int = 1, bundlewait: int = 5, in_memory: bool = False, no_confirm: bool = False, poll: int = 30, address: Tuple[str, int] = ('localhost', 50001), auth: str = '<not-secure>', max_retries: int = 0, eager: bool = False, redirect_failures: IO | None = None, evict_after: int = 600, tls: TLSConfig | None = None, **file_options) → None[source]

Run server with tasks from a local file path, run until complete.

Parameters:

  • path (str) – Path to file containing command-line tasks.

  • task_cores (int, optional) – Default number of cores to use for each task (default: none). May be overridden by inline-comment.

  • task_memory (int, optional) – Default memory in bytes to use for each task (default: none). May be overridden by inline-comment.

  • task_timeout (int, optional) – Task-level walltime limit in seconds (default: none).

  • bundlesize (int, optional) – Size of task bundles. See DEFAULT_BUNDLESIZE.

  • bundlewait (int, optional) – Waiting period before forcing task bundle push. See DEFAULT_BUNDLEWAIT.

  • in_memory (bool, optional) – If True, revert to basic in-memory queue.

  • no_confirm (bool, optional) – If True, do not check for client confirmation messages.

  • poll (int, optional) – Polling interval in seconds between database queries if no tasks are available. See DEFAULT_SERVER_POLL.

  • address (tuple, optional) – Bind address for server with port number. See DEFAULT_BIND and DEFAULT_PORT.

  • auth (str, optional) – Server authentication key. See DEFAULT_AUTH.

  • max_retries (int, optional) – Number of allowed task retries. See DEFAULT_ATTEMPTS.

  • eager (bool, optional) – When enabled tasks are retried immediately ahead scheduling new tasks. See DEFAULT_EAGER_MODE.

  • redirect_failures (bool, optional) – Open file descriptor to write failed tasks.

  • evict_after (int, optional) – Period in seconds to wait before evicting clients that miss heartbeats. See DEFAULT_EVICT.

  • tls – (TLSConfig, optional): TLS configuration for queue interface. Clients must connect with compatible configuration. See security documentation for details.

Keyword Arguments:

file_options (Any, optional) – Forwarded to open() function.

Example

>>> from hypershell.server import serve_file
>>> serve_from('/tmp/tasks.in', auth='my-secret-key', bundlesize=10)

See also


serve_forever(bundlesize: int = 1, in_memory: bool = False, no_confirm: bool = False, poll: int = 30, address: Tuple[str, int] = ('localhost', 50001), auth: str = '<not-secure>', max_retries: int = 0, eager: bool = False, redirect_failures: IO = None, evict_after: int = 600, tls: TLSConfig | None = None) → None[source]

Run server forever.

Parameters:

  • bundlesize (int, optional) – Size of task bundles. See DEFAULT_BUNDLESIZE.

  • in_memory (bool, optional) – If True, revert to basic in-memory queue.

  • no_confirm (bool, optional) – If True, do not check for client confirmation messages.

  • address (tuple, optional) – Bind address for server with port number. See DEFAULT_BIND and DEFAULT_PORT.

  • auth (str, optional) – Server authentication key. See DEFAULT_AUTH.

  • max_retries (int, optional) – Number of allowed task retries. See DEFAULT_ATTEMPTS.

  • poll (int, optional) – Polling interval in seconds between database queries if no tasks are available. See DEFAULT_SERVER_POLL.

  • eager (bool, optional) – When enabled tasks are retried immediately ahead scheduling new tasks. See DEFAULT_EAGER_MODE.

  • redirect_failures (bool, optional) – Open file descriptor to write failed tasks.

  • evict_after (int, optional) – Period in seconds to wait before evicting clients that miss heartbeats. See DEFAULT_EVICT.

  • tls – (TLSConfig, optional): TLS configuration for queue interface. Clients must connect with compatible configuration. See security documentation for details.

Example

>>> from hypershell.server import serve_forever
>>> serve_forever(address=('0.0.0.0', 54321), auth='my-secret-key',
...               max_retries=2, eager=True, evict_after=600)

See also

Classes


class ServerThread(source: Iterable[str] = None, task_cores: int = None, task_memory: int = None, task_timeout: int = None, bundlesize: int = 1, bundlewait: int = 5, in_memory: bool = False, no_confirm: bool = False, poll: int = 30, forever_mode: bool = False, restart_mode: bool = False, address: Tuple[str, int] = ('localhost', 50001), auth: str = '<not-secure>', max_retries: int = 0, eager: bool = False, redirect_failures: IO = None, evict_after: int = 600, tls: TLSConfig | None = None)[source]

Bases: Thread

Run server within dedicated thread.

Parameters:

  • source (Iterable[str], optional) – Any iterable of command-line tasks. A new source results in a SubmitThread populating either the database or the queue directly depending on in_memory.

  • task_cores (int, optional) – Default number of cores to use for each task (default: none). May be overridden by inline-comment.

  • task_memory (int, optional) – Default memory in bytes to use for each task (default: none). May be overridden by inline-comment.

  • task_timeout (int, optional) – Task-level walltime limit in seconds (default: none).

  • bundlesize (int, optional) – Size of task bundles. See DEFAULT_BUNDLESIZE.

  • bundlewait (int, optional) – Waiting period before forcing task bundle push. See DEFAULT_BUNDLEWAIT.

  • restart_mode (bool, optional) – If source is empty, this option allows for the server to continue with scheduling from the database until complete. Conflicts with in_memory. Default is False.

  • forever_mode (bool, optional) – Regardless of source, if enabled schedule forever. Conflicts with restart_mode and in_memory. Default is False.

  • in_memory (bool, optional) – If True, revert to basic in-memory queue.

  • no_confirm (bool, optional) – If True, do not check for client confirmation messages.

  • poll (int, optional) – Polling interval in seconds between database queries if no tasks are available. See DEFAULT_SERVER_POLL.

  • address (tuple, optional) – Bind address for server with port number. See DEFAULT_BIND and DEFAULT_PORT.

  • auth (str, optional) – Server authentication key. See DEFAULT_AUTH.

  • max_retries (int, optional) – Number of allowed task retries. See DEFAULT_ATTEMPTS.

  • eager (bool, optional) – When enabled tasks are retried immediately ahead scheduling new tasks. See DEFAULT_EAGER_MODE.

  • redirect_failures (IO, optional) – Open file descriptor to write failed tasks.

  • evict_after (int, optional) – Period in seconds to wait before evicting clients that miss heartbeats. See DEFAULT_EVICT.

  • tls – (TLSConfig, optional): TLS configuration for queue interface. Clients must connect with compatible configuration. See security documentation for details.

Example

>>> from hypershell.server import ServerThread
>>> server = ServerThread.new(restart_mode=True, auth='my-secret-key')
>>> server.join()

See also

classmethod new(*args, **kwargs) → Thread

Initialize and start the thread.

start() → None[source]

Override default start method to wait for queue to be ready.

join(timeout: float | None = None) → None

Calls Thread.join but re-raises exceptions.

stop(wait: bool = False, timeout: int = None) → None[source]

Stop child threads before main thread.


Warning

While nothing prevents you from creating more than one ServerThread it should be considered an error to do so. The point of the thread is to provide for asynchronous operations not to allow for multiple instances. There are several unavoidable process-wide global considerations such as signal handling, resource tracking, and encryption key management that make it an error to spawn multiple instances of the thread with differing parameters.

Constants


DEFAULT_BUNDLESIZE: Final[int] = 1

Default size for task bundles.

DEFAULT_EVICT: Final[int] = 600

Default client eviction period in seconds.

DEFAULT_ATTEMPTS: Final[int] = 1

Default number of attempts for task retries.

DEFAULT_EAGER_MODE: Final[bool] = False

When enabled tasks are retried immediately ahead scheduling new tasks.

DEFAULT_SERVER_POLL: Final[int] = 30

Default polling interval in seconds between database queries if no tasks are available.

DEFAULT_BIND: Final[str] = 'localhost'

Default bind address for server.

DEFAULT_PORT: Final[int] = 50001

Default port number for server.

DEFAULT_AUTH: Final[str] = '<not-secure>'

Default authentication key for server (DO NOT USE THIS).