Configuration

Resources can be declared in code with @queue.worker_resource() or loaded from a TOML file. Both approaches support the same options.

TOML configuration file

Define resources in a TOML file and load them at startup:

# resources.toml

[resources.config]
factory = "myapp.resources:load_config"
scope = "worker"

[resources.db]
factory = "myapp.resources:create_engine"
teardown = "myapp.resources:close_engine"
health_check = "myapp.resources:check_db"
health_check_interval = 30.0
max_recreation_attempts = 3
scope = "worker"
depends_on = ["config"]

[resources.session]
factory = "myapp.resources:create_session"
scope = "pooled"
pool_size = 20
pool_min = 5
acquire_timeout = 5.0
depends_on = ["db"]

Load before starting the worker:

queue.load_resources("resources.toml")

The factory, teardown, and health_check values are import paths. Both formats are accepted:

• "myapp.resources:create_engine" — colon separator (preferred)
• "myapp.resources.create_engine" — dot separator

On Python 3.11+ the TOML parser is built-in. On earlier versions, install tomli:

pip install tomli

TOML resource options

Pool configuration

Pool parameters apply only to pooled resources (scope = "pooled"); setting pool_size or pool_min on any other scope raises. They control the bounded pool that manages concurrent instances.

@queue.worker_resource(
    "session",
    scope="pooled",
    pool_size=20,
    pool_min=5,
    acquire_timeout=5.0,
    max_lifetime=1800.0,
)
def create_session(db):
    return db()

Setting pool_min > 0 causes the pool to prewarm instances at worker startup. This avoids the cold-start latency on the first burst of tasks.

Frozen resources

Wrap a resource in a read-only wrapper to prevent accidental mutation. (This is unrelated to the Resource Proxies layer — "wrapper" here just means attribute writes raise.)

@queue.worker_resource("config", frozen=True)
def load_config():
    return AppConfig.from_env()

Attempts to set attributes on a frozen resource raise AttributeError. This is useful for configuration objects that should be treated as immutable after initialization.

Hot reload

Mark resources as reloadable to update them without restarting the worker:

@queue.worker_resource("feature_flags", reloadable=True)
def load_flags():
    return FeatureFlags.from_remote()

Trigger a reload by sending SIGHUP to the worker process:

kill -HUP <worker-pid>

Or via the CLI:

flexiq reload --pid <worker-pid>
flexiq reload --pid <worker-pid> --resource feature_flags  # reload one resource

Or programmatically from application code — reload everything reloadable, or name specific resources:

results = queue.reload_resources()
# {"feature_flags": True}

queue.reload_resources(["feature_flags"])  # just one

reload_resources() returns an empty dict when no worker is running in the process (there is no live resource runtime to reload). An async twin, areload_resources(), is available for async code.

Only resources declared with reloadable=True are affected. Non-reloadable resources are left running — no teardown or reconnection.

Resources are reloaded in the same topological order as initialization. If a reloadable resource depends on another reloadable resource, both are reloaded in dependency order.

Programmatic resource registration

load_resources() and @worker_resource() both call register_resource() internally. You can call it directly for full control:

from flexiq.resources.definition import ResourceDefinition, ResourceScope

queue.register_resource(ResourceDefinition(
    name="db",
    factory=create_db,
    teardown=close_db,
    health_check=check_db,
    health_check_interval=30.0,
    scope=ResourceScope.WORKER,
    depends_on=["config"],
    reloadable=True,
))

register_resource() must be called before run_worker().