Skip to content

compas_eve.ghpython ¤

Classes¤

BackgroundWorker ¤

BackgroundWorker(
    ghenv: PythonEnvironment,
    long_running_function: Callable | None = None,
    dispose_function: Callable | None = None,
    auto_set_done: bool = True,
    args=(),
)

Background worker simplifies the creation of long-running tasks inside Grasshopper.

A long-running task is any piece of code that will run for an extended period of time, for example, a very complex calculation, or loading a very large data file, etc.

To use it, write your long-running function in a Grasshopper GHPython component, and pass it as the input to the background worker component. The worker will continue working without blocking the UI.

The following is an example of a long-running function that updates the progress while it runs.

import time


def do_something_long_and_complicated(worker):
    # Result can be of any data type
    result = 0

    for i in range(50):
        worker.current_value = i
        result += i
        worker.display_progress(i / (50 - 1))
        time.sleep(0.01)

    worker.display_message("Done!")

    return result

Parameters:

  • ghenv (PythonEnvironment) –

    Grasshopper environment object

  • long_running_function (Callable | None, default: None ) –

    This function will be the main entry point for the long-running task.

  • dispose_function (Callable | None, default: None ) –

    If defined, this function will be called when the worker is disposed. It can be used for clean-up tasks and resource deallocation.

  • auto_set_done (bool, default: True ) –

    If true, the worker state will be automatically set to Done after the function returns. Defaults to True.

  • args –

    List or tuple of arguments for the invocation of the long_running_function. Defaults to ().

Referenced by: Returned by:

Functions¤

display_message ¤
display_message(message: str)

Display a message in the component without triggering a solution expiration.

Parameters:

  • message (str) –

    Message to display.

display_progress ¤
display_progress(progress: float)

Display a progress indicator in the component.

Parameters:

  • progress (float) –

    Float between 0..1 indicating progress of completion.

dispose ¤
dispose()

Invoked when the worker is being disposed.

instance_by_component classmethod ¤
instance_by_component(
    ghenv: PythonEnvironment,
    long_running_function: Callable | None = None,
    dispose_function: Callable | None = None,
    auto_set_done: bool = True,
    force_new: bool = False,
    args=(),
)

Get the worker instance assigned to the component.

This will get a persistant instance of a background worker for a given component. The parameter force_new can be set to True to request a new instance to be created.

Parameters:

  • ghenv (PythonEnvironment) –

    Grasshopper environment object

  • long_running_function (Callable | None, default: None ) –

    This function will be the main entry point for the long-running task.

  • dispose_function (Callable | None, default: None ) –

    If defined, this function will be called when the worker is disposed. It can be used for clean-up tasks and resource deallocation.

  • auto_set_done (bool, default: True ) –

    If true, the worker state will be automatically set to Done after the function returns. Defaults to True.

  • force_new (bool, default: False ) –

    Force the creation of a new background worker, by default False.

  • args (tuple, default: () ) –

    List or tuple of arguments for the invocation of the long_running_function. Defaults to ().

Returns:

  • BackgroundWorker –

    Instance of the background worker of the current component.

is_done ¤
is_done()

Indicate whether the worker is done or not.

is_working ¤
is_working()

Indicate whether the worker is currently working or not.

request_cancellation ¤
request_cancellation()

Mark the current worker as cancelled, so that the background task can stop processing.

set_internal_state_to_cancelled ¤
set_internal_state_to_cancelled()

Set the internal state to cancelled.

set_internal_state_to_done ¤
set_internal_state_to_done(result: Any)

Set the internal state to done, which indicates the worker has completed.

set_internal_state_to_working ¤
set_internal_state_to_working()

Set the internal state to working.

start_work ¤
start_work()

Start the background processing thread where work will be performed.

stop_instance_by_component classmethod ¤
stop_instance_by_component(ghenv: PythonEnvironment)

Stops the worker instance assigned to the component.

If there is no worker running, it will do nothing.

Parameters:

  • ghenv (PythonEnvironment) –

    Grasshopper environment object

update_result ¤
update_result(result: Any, delay: int = 1)

Update the result of the worker.

This will update the result of the worker, and trigger a solution expiration of the Grasshopper component.

Parameters:

  • result (Any) –

    Result of the worker.

  • delay (int, default: 1 ) –

    Delay (in milliseconds) before updating the component, by default 1.

Functions¤

error ¤

error(component: IGH_Component, message: str)

Add an error message to the component.

Parameters:

  • component (IGH_Component) –

    The component instance. Pre-Rhino8 use self. Post-Rhino8 use ghenv.Component.

  • message (str) –

    The message to display.

message ¤

message(component: IGH_Component, message: str)

Add a text that will appear under the component.

Parameters:

  • component (IGH_Component) –

    The component instance. Pre-Rhino8 use self. Post-Rhino8 use ghenv.Component.

  • message (str) –

    The message to display.

remark ¤

remark(component: IGH_Component, message: str)

Add a remark message to the component.

Parameters:

  • component (IGH_Component) –

    The component instance. Pre-Rhino8 use self. Post-Rhino8 use ghenv.Component.

  • message (str) –

    The message to display.

warning ¤

warning(component: IGH_Component, message: str)

Add a warning message to the component.

Parameters:

  • component (IGH_Component) –

    The component instance. Use ghenv.Component.

  • message (str) –

    The message to display.