Resources

Jobs and workers state what they need and what they offer as resources, for example a programming language. The shared package defines resources and their matching rules. See the resources documentation.

This module converts between the shared package’s momotor.shared.resources.Resources objects and the Resource protocol messages that travel over the wire:

from momotor.rpc.resources import message_to_resources, resources_to_message
from momotor.shared.resources import Resources

resources = Resources.from_string('language: python')
messages = resources_to_message(resources)
restored = message_to_resources(messages)

resources_to_message() returns None for an empty set of resources. message_to_resources() accepts None and returns an empty set, so the two functions round-trip optional message fields without extra checks.

Read remote and global resource settings

Added in version 7.0.0.

The ClientStub has two resource reads. Both take google.protobuf.empty_pb2.Empty and return GetResourcesResponse. Both require authentication with the resources permission. The client permission for job submission is not required.

getResources returns the authenticated caller’s own remote resource settings. It does not merge global resources into the result or accept another remote’s identifier. Sessions authenticated as the same remote share these settings.

getGlobalResources returns the effective aggregate resource requirements and restrictions contributed by remotes with use_resources_globally=True. Configured remotes contribute even while disconnected. Remotes with the flag set to false do not contribute. The response contains only the aggregate resources, without individual remote records or identities. These resources describe requirements and restrictions, not worker capacity or currently free resources.

External edits to stored remote settings become visible in global snapshots after the broker refreshes the affected remote. A read does not guarantee an immediate refresh of those settings.

The response’s resource field uses the existing Resource encoding, including positive, optional, and excluded tags. An empty resource list with no exception is a successful empty result. Check the exception before converting the resources:

from google.protobuf.empty_pb2 import Empty
from momotor.rpc.exception import raise_message_exception
from momotor.rpc.resources import message_to_resources

response = await client.getResources(Empty())
raise_message_exception(response)
own_resources = message_to_resources(response.resource)

Here, client is a stub on an authenticated channel, as shown in Authentication. Call client.getGlobalResources(Empty()) to read global resources with the same response handling.

Each read is a point-in-time snapshot. A later updateResources call is a separate operation. The reads provide no atomic ownership or rollback. Concurrent writers authenticated as the same remote must coordinate their updates. updateResources continues to add, remove, or replace resources. It does not list them, and resource reads are not part of statistics JSON.

Broker and client rollout

Both reads need broker handlers. The generated ClientBase declares getResources and getGlobalResources as abstract methods. Broker implementations must add both handlers when upgrading this protocol dependency. An older implementation that lacks these methods cannot instantiate the new base class.

An older running broker can report UNIMPLEMENTED or another RPC failure for these calls. A transport failure or a response with exception set is distinct from a successful empty result. Recovery code must retain existing exclusions when the read is unavailable or fails. It must not interpret that failure as an empty resource set.

API reference

momotor.rpc.resources.message_to_resources(resources_messages)

Convert an iterable of Resource messages into a Resources

Parameters:

resources – The resource messages

Return type:

Resources

Returns:

Resources object for the messages

momotor.rpc.resources.resources_to_message(resources)

Convert a Resources object into a list of Resource messages

Parameters:

resources (Resources) – The resources

Return type:

list[Resource] | None

Returns:

The message