Manager

This class owns the cache service's core behavior, including reading/writing cached outputs, maintaining cache metadata timestamps, and coordinating serialized cache population with reservations. It defines the policy for cache population, allowing the service layer to remain thin and repository implementations to focus solely on persistence.

Methods

---

Get()

@classmethod
def Get(
    ctx: context.Context,
    request: *cacheservicepb.GetCacheRequest
) - > *CacheEntry, error

Fetches a cache entry based on the provided request. This method retrieves cached outputs and their associated metadata.

Parameters

Name	Type	Description
ctx	context.Context	The context for the request, used for cancellation and deadlines.
request	*cacheservicepb.GetCacheRequest	The request containing the necessary information to identify and retrieve a cache entry.

Returns

Type	Description
*CacheEntry, error	The retrieved cache entry and an error if the operation fails.

---

Put()

@classmethod
def Put(
    ctx: context.Context,
    request: *cacheservicepb.PutCacheRequest
) - > error

Stores a cache entry with the provided data. This method persists new or updated cached outputs.

Parameters

Name	Type	Description
ctx	context.Context	The context for the request, used for cancellation and deadlines.
request	*cacheservicepb.PutCacheRequest	The request containing the cache entry data to be stored.

Returns

Type	Description
error	An error if the operation fails.

---

Delete()

@classmethod
def Delete(
    ctx: context.Context,
    request: *cacheservicepb.DeleteCacheRequest
) - > error

Removes a cache entry based on the provided request. This method deletes cached outputs and their metadata.

Parameters

Name	Type	Description
ctx	context.Context	The context for the request, used for cancellation and deadlines.
request	*cacheservicepb.DeleteCacheRequest	The request containing the necessary information to identify and delete a cache entry.

Returns

Type	Description
error	An error if the operation fails.

---

GetOrExtendReservation()

@classmethod
def GetOrExtendReservation(
    ctx: context.Context,
    request: *cacheservicepb.GetOrExtendReservationRequest,
    now: time.Time
) - > *cacheservicepb.Reservation, error

Retrieves an existing reservation or creates a new one, extending its heartbeat if necessary. This method coordinates serialized cache population.

Parameters

Name	Type	Description
ctx	context.Context	The context for the request, used for cancellation and deadlines.
request	*cacheservicepb.GetOrExtendReservationRequest	The request containing details for getting or extending a reservation.
now	time.Time	The current time, used for calculating reservation expiration and heartbeat.

Returns

Type	Description
*cacheservicepb.Reservation, error	The reservation object and an error if the operation fails.

---

ReleaseReservation()

@classmethod
def ReleaseReservation(
    ctx: context.Context,
    request: *cacheservicepb.ReleaseReservationRequest
) - > error

Releases a previously held reservation. This method allows other processes to acquire a reservation for cache population.

Parameters

Name	Type	Description
ctx	context.Context	The context for the request, used for cancellation and deadlines.
request	*cacheservicepb.ReleaseReservationRequest	The request containing the necessary information to identify and release a reservation.

Returns

Type	Description
error	An error if the operation fails.

---

resolvedHeartbeat()

@classmethod
def resolvedHeartbeat(
    requested: *durationpb.Duration
) - > time.Duration

Calculates the effective heartbeat duration for a reservation, considering a requested duration and system-defined maximums. This ensures heartbeats do not exceed configured limits.

Parameters

Name	Type	Description
requested	*durationpb.Duration	The requested heartbeat duration for the reservation.

Returns

Type	Description
time.Duration	The resolved heartbeat duration, clamped by the maximum reservation heartbeat interval.

---