hypershell.client


Directly embed client as either a dedicated ClientThread or using the provided high-level run_client() function.

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.

Functions


run_client(num_threads: int = 1, bundlesize: int = 1, bundlewait: int = 5, address: Tuple[str, int] = ('localhost', 50001), auth: str = '<not-secure>', template: str = '{}', redirect_output: IO = None, redirect_errors: IO = None, capture: bool = False, monitor: bool = False, cores: int = None, memory: int = None, heartrate: int = 10, delay_start: float = 0, no_confirm: bool = False, client_timeout: int = None, task_timeout: int = None, task_signalwait: int = 10, ratelimit: int = None, tls: TLSConfig | None = None) → None[source]

Run client until disconnect signal received or client_timeout reached.

Parameters:

  • num_threads (int, optional) – Number of executor threads (use 0 for auto-detection based on cores). See DEFAULT_NUM_THREADS.

  • bundlesize (int optional) – Size of task bundles returned to server. See DEFAULT_BUNDLESIZE.

  • bundlewait (int optional) – Waiting period in seconds before forcing return of task bundle to server. See DEFAULT_BUNDLEWAIT.

  • address (tuple, optional) – Server host address for server with port number. See DEFAULT_HOST and DEFAULT_PORT.

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

  • template (str, optional) – Template command pattern. See DEFAULT_TEMPLATE.

  • redirect_output (IO, optional) – Optional file-like object for <stdout> redirect.

  • redirect_errors (IO, optional) – Optional file-like object for <stderr> redirect.

  • heartrate (int, optional) – Period in seconds to wait between heartbeats. See DEFAULT_HEARTRATE,

  • capture (bool, optional) – Isolate task <stdout> and <stderr> in discrete files (default: False).

  • monitor (bool, optional) – Track CPU cores and memory usage of each task (default: False).

  • cores (int, optional) – Set core limit for client (default: all available cores).

  • memory (int, optional) – Set memory limit for client (default: all available memory).

  • delay_start (float, optional) – Delay in seconds before connecting to server. See DEFAULT_DELAY.

  • no_confirm (bool, optional) – Disable client confirmation of tasks received.

  • client_timeout (int, optional) – Timeout in seconds before disconnecting from server. By default, the client waits for server tor request disconnect.

  • task_timeout (int, optional) – Task-level walltime limit in seconds. By default, the client waits indefinitely on tasks.

  • task_signalwait (int, optional) – Signal escalation waiting period in seconds on task timeout. See DEFAULT_SIGNALWAIT.

  • ratelimit (int, optional) – Maximum allowed tasks per second (default: none). There is no limit on task throughput unless specified.

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

Example

>>> from hypershell.client import run_client
>>> run_client(num_threads=16, address=('localhost', 54321),
...            auth='my-secret-key', capture=True)

See also

Classes


class ClientThread(num_threads: int = 1, bundlesize: int = 1, bundlewait: int = 5, address: Tuple[str, int] = ('localhost', 50001), auth: str = '<not-secure>', template: str = '{}', redirect_output: IO = None, redirect_errors: IO = None, heartrate: int = 10, capture: bool = False, monitor: bool = False, cores: int = None, memory: int = None, delay_start: float = 0, no_confirm: bool = False, client_timeout: int = None, task_timeout: int = None, task_signalwait: int = 10, ratelimit: int = None, tls: TLSConfig | None = None)[source]

Bases: Thread

Run client within dedicated thread. Run until either disconnect requested from server or client_timeout reached. Will also halt for SIGUSR2 signal on UNIX.

Parameters:

  • num_threads (int, optional) – Number of executor threads (use 0 for auto-detection based on cores). See DEFAULT_NUM_THREADS.

  • bundlesize (int optional) – Size of task bundles returned to server. See DEFAULT_BUNDLESIZE.

  • bundlewait (int optional) – Waiting period in seconds before forcing return of task bundle to server. See DEFAULT_BUNDLEWAIT.

  • address (tuple, optional) – Server host address for server with port number. See DEFAULT_HOST and DEFAULT_PORT.

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

  • template (str, optional) – Template command pattern. See DEFAULT_TEMPLATE.

  • redirect_output (IO, optional) – Optional file-like object for <stdout> redirect.

  • redirect_errors (IO, optional) – Optional file-like object for <stderr> redirect.

  • heartrate (int, optional) – Period in seconds to wait between heartbeats. See DEFAULT_HEARTRATE,

  • capture (bool, optional) – Isolate task <stdout> and <stderr> in discrete files (default: False).

  • monitor (bool, optional) – Track CPU cores and memory usage of each task (default: False).

  • cores (int, optional) – Set core limit for client (default: all available cores).

  • memory (int, optional) – Set memory limit for client (default: all available memory).

  • delay_start (float, optional) – Delay in seconds before connecting to server. See DEFAULT_DELAY.

  • no_confirm (bool, optional) – Disable client confirmation of tasks received.

  • client_timeout (int, optional) – Timeout in seconds before disconnecting from server. By default, the client waits for server tor request disconnect.

  • task_timeout (int, optional) – Task-level walltime limit in seconds. By default, the client waits indefinitely on tasks.

  • task_signalwait (int, optional) – Signal escalation waiting period in seconds on task timeout. See DEFAULT_SIGNALWAIT.

  • ratelimit (int, optional) – Maximum allowed tasks per second (default: none). There is no limit on task throughput unless specified.

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

Example

>>> from hypershell.client import ClientThread
>>> client = ClientThread.new(num_threads=16, address=('localhost', 54321),
...                           auth='my-secret-key', capture=True)
>>> client.join()

See also

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

Initialize and start the thread.

start()

Start the thread’s activity.

It must be called at most once per thread object. It arranges for the object’s run() method to be invoked in a separate thread of control.

This method will raise a RuntimeError if called more than once on the same thread object.

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.


Important Note

While nothing prevents you from creating more than one ClientThread 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_NUM_THREADS: Final[int] = 1

Default number of executor threads per client.

DEFAULT_TEMPLATE: Final[str] = '{}'

Default command pattern for template expansion.

DEFAULT_BUNDLESIZE: Final[int] = 1

Default size of task bundles.

DEFAULT_BUNDLEWAIT: Final[int] = 5

Default waiting period before forcing task bundle push.

DEFAULT_SIGNALWAIT: Final[int] = 10

Default signal escalation wait period in seconds.

DEFAULT_HEARTRATE: Final[int] = 10

Period in seconds to wait between heartbeats.

DEFAULT_DELAY: Final[int] = 0

Default delay in seconds on client startup.

DEFAULT_HOST: Final[str] = 'localhost'

Default host for server connection.

DEFAULT_PORT: Final[int] = 50001

Default port for server connection.

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

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