Callbacks¶

A callback is a function that is attached to a runium.core.Task object and gets executed as soon as the task finishes.

Callbacks are executed in the same Thread/Process as the Task that calls them. As a result they are non-blocking.

on_finished¶

Task.on_finished(fn, updates_result=False)

Runs the callback after the task has been executed successfully or after an exception was raised.

Accepts a callable with the task’s success and error results as its only arguments.

If the task was successfull (no exceptions were raised) then the success argument will contain the task’s return and the error argument will be None.

If the task is unsuccessfull (an exception was raised) then the error argument will contain the exception object and success will be None.

Parameters

fn – The callable to be executed with success and error as its only arguments.
updates_result – (Optional) If this is True then the task’s result will be replaced with whatever is returned by the callable.

Example:

def send_email():
    print("Sending email...")
    return "Email sent."


# The callback must have the success and error arguments.
def callback(success, error):
    if success:
        return True
    elif error:
        return "An error occurred."


# Attach the callback like this
async_task = runium.new_task(send_email).on_finished(callback).run()


# You may also choose to get the result of the callback instead of the task
# by setting the parameter updates_result to True.
async_task = runium.new_task(send_email).on_finished(
    callback, updates_result=True).run()

# This will return True
async_task.result()

on_success¶

Task.on_success(fn, updates_result=False)

Runs the callback after the task has been executed successfully and no exceptions were raised.

Accepts a callable with the task’s result as its only argument.

Parameters

fn – The callable to be executed with success as its only argument.
updates_result – (Optional) If this is True then the task’s result will be replaced with whatever is returned by the callable.

Example:

def send_email():
    print("Sending email...")
    return "Email sent."


# The callback must have the success argument.
def callback(success):
    return ("Success!")

# Attach the callback like this
async_task = runium.new_task(send_email).on_success(callback).run()

# This callback is often used together with on_error callback:
async_task = runium.new_task(
    send_email
).on_success(
    callback
).on_error(
    error_callback
).run()

on_error¶

Task.on_error(fn, updates_result=False)

Runs the callback after an exception was raised by the task.

Accepts a callable with the task’s exception object as its only argument.

Parameters

fn – The callable to be executed with error as its only argument.
updates_result – (Optional) If this is True then the task’s result will be replaced with whatever is returned by the callable.

Example:

def send_email():
    raise Exception("Email was not sent.)


# The callback must have the error argument.
def callback(error):
    resend_email()


# Attach the callback like this
async_task = runium.new_task(send_email).on_error(callback).run()

# This callback is often used together with on_success callback:
async_task = runium.new_task(
    send_email
).on_success(
    callback
).on_error(
    error_callback
).run()

on_iter¶

Task.on_iter(fn, updates_result=False)

Runs the callback every time the task is beeing executed successfully or after an exception was raised.

Accepts a callable with the task’s success and error results as its only arguments.

If the task was successfull (no exceptions were raised) then the success argument will contain the task’s return and the error argument will be None.

If the task is unsuccessfull (an exception was raised) then the error argument will contain the exception object and success will be None.

The difference between this type of callback and all the others is that the other callbacks will run only once after the task has been executed no matter how many times we’ve set it to run. But an on_iter callback will run on every iteration if the task is to be executed many times.

Parameters

fn – The callable to be executed with success and error as its only arguments: fn(success, error)
updates_result – (Optional) If this is True then the task’s result will be replaced with whatever is returned by the callable.

Example:

# The callback must have the success and error arguments.
def callback(success, error):
    if success:
        print(success)
        return True
    elif error:
        print(error)
        return "An error occurred."

# The callback will be executed 3 times.
async_task = runium.new_task(send_email).on_iter(callback).run(times=3)

add_done_callback¶

This is not a Runium method but since Task.run() returns a Future object, you can also add callbacks using this method. But you have to call run() first before using this method. Read the documentation about it here: add_done_callback()