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.