Background Jobs

Background Jobs are long-running, continuous tasks that start with the application and are intended to run while the application is active. They operate independently of request handling and are designed for persistent processes such as data producers or external resource watchers.

A job may terminate at any point, and once it does, it will not be started again.

During application shutdown, each background job is cancelled. This cancellation causes an asyncio.CancelledError to be raised inside the job, signalling it to stop. It is the developer’s responsibility to handle this correctly to avoid data inconsistencies. Techniques such as asyncio.shield can be used to protect critical sections.

If any job raises an exception other than asyncio.CancelledError, it is treated as a fatal error. In this case, the entire application is shut down to prevent running in an inconsistent state.

How to create a background job

In order to create a background job you need to create a BackgroundJob object and use it to decorate a function with the logic of your job using @job.register.

import asyncio

from arconq_sdk import Dependency, Logger, BackgroundJob
from containers.container import Container
from services.messaging_service import MessagingService

job = BackgroundJob()

@job.register(name="example background job")
async def example_background_job(
    logger: Logger = Dependency(Container.logger), 
    messaging_service: MessagingService = Dependency(Container.messaging_service)
):
    while True:
        await messaging_service.send_message()
        logger.info("Message has been sent")
        await asyncio.sleep(10.0)

The next step is to register the background job.

@arconq_app
def main(
    container: Container,
    app_builder: AppBuilder = Dependency(Container.app_builder),
) -> None:
    app_builder.configure_arconq(container)

    app_builder.add_background_job(container, example_background_job, example_background_job.job)

    app = app_builder.build_app()
    app.run()