Unit Function Decorators

These function decorators can be added to member functions of an ezmsg Unit or Collection.

@ezmsg.core.subscriber(stream, zero_copy=False)

A decorator for a method that subscribes to a stream in the task/messaging thread.

An async function will run once per message received from the InputStream it subscribes to. A function can have both @subscriber and @publisher decorators.

Parameters:

• stream (InputStream) – The input stream to subscribe to

• zero_copy (bool) – Whether to use zero-copy message passing (default: False)

Returns:

Decorated function that can subscribe to the stream

Return type:

Callable

Raises:

ValueError – If stream is not an InputStream

Example usage:

INPUT = ez.InputStream(Message)

@subscriber(INPUT)
async def print_message(self, message: Message) -> None:
   print(message)

@ezmsg.core.publisher(stream)

A decorator for a method that publishes to a stream in the task/messaging thread.

An async function will yield messages on the designated OutputStream. A function can have both @subscriber and @publisher decorators.

Parameters:

stream (OutputStream) – The output stream to publish messages to

Returns:

Decorated function that can publish to the stream

Return type:

Callable

Raises:

ValueError – If stream is not an OutputStream

Example usage:

from collections.abc import AsyncGenerator

OUTPUT = OutputStream(ez.Message)

@publisher(OUTPUT)
async def send_message(self) -> AsyncGenerator:
   message = Message()
   yield(OUTPUT, message)

@ezmsg.core.main(func)

A decorator which designates this function to run as the main thread for this Unit.

A Unit may only have one main function. The main function runs independently of the message processing and is typically used for initialization, background processing, or cleanup tasks.

Parameters:

func (Callable) – The function to designate as main

Returns:

The decorated function

Return type:

Callable

@ezmsg.core.thread(func)

A decorator which designates this function to run as a background thread for this Unit.

Thread functions run concurrently with the main message processing and can be used for background tasks, monitoring, or other concurrent operations.

Parameters:

func (Callable) – The function to run as a background thread

Returns:

The decorated function

Return type:

Callable

@ezmsg.core.task(func)

A decorator which designates this function to run as a task in the task/messaging thread.

Task functions are part of the main message processing pipeline and are executed within the unit’s primary execution context.

Parameters:

func (Callable) – The function to run as a task

Returns:

The decorated function

Return type:

Callable

@ezmsg.core.process(func)

A decorator which designates this function to run in its own process.

Process functions run in separate processes for isolation and can be used for CPU-intensive operations or when process isolation is required.

Parameters:

func (Callable) – The function to run in its own process

Returns:

The decorated function

Return type:

Callable

@ezmsg.core.timeit(func)

A decorator that logs the execution time of the decorated function.

ezmsg will log the amount of time this function takes to execute to the ezmsg logger. This is useful for performance monitoring and optimization. The execution time is logged in milliseconds.

Note

Use the @profile_subpub or @profile_method decorators from ezmsg-sigproc for more detailed profiling that is stored in a dedicated profiling log file.

Parameters:

func (Callable) – The function to time

Returns:

The decorated function with timing functionality

Return type:

Callable