blob: 8280f875a99a6a51018431825320563eb45e94a9 [file] [log] [blame]
// Copyright 2019 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library fuchsia.sys2;
using zx;
using fuchsia.component;
const uint32 MAX_WORK_ID_LENGTH = 100;
alias WorkId = string:MAX_WORK_ID_LENGTH;
/// Different ways to specify when to schedule a work item for the first time.
flexible union Start {
/// A non-negative delay to wait before scheduling work.
1: zx.duration delay;
/// A fixed point in time to start scheduling work, interpreted like `ZX_CLOCK_MONOTONIC`:
/// number of nanoseconds since the system was powered on.
2: zx.time monotonic_time;
/// Parameters for a new piece of work to be scheduled.
table WorkRequest {
/// Time when corresponding work item should be _first_ scheduled.
1: Start start;
/// Delay between repeated schedulings of corresponding work item. This is left unspecified for
/// one-shot work that should not repeat. Repeating work items are rescheduled indefinitely
/// until it is canceled.
2: zx.duration period;
/// Framework service: API for scheduling and canceling work. Each component instance can access
/// work items that it has scheduled (but not others' scheduled work items). Work items are
/// scheduled _roughly_ at the specified time and frequency; the service implementation may specify
/// its notion of _roughly_, and may provide a configuration API to tune this notion.
/// Each scheduled work item is identified by a client-provided `WorkId`. Each scheduled work item
/// has a `WorkId` that is unique with respect to scheduled work items belonging to the same
/// component instance.
protocol WorkScheduler {
/// Schedule a new work item identified by `work_id`. The work item is to be scheduled roughly
/// at the time corresponding to `work_request.start`. When `work_request.period` is specified,
/// reschedule work roughly every `work_request.period` until the the work item is canceled.
ScheduleWork(WorkId work_id, WorkRequest work_request) -> () error fuchsia.component.Error;
/// Cancel the scheduled work item specified by `work_id`.
CancelWork(WorkId work_id) -> () error fuchsia.component.Error;
/// Component-exposed service: Work scheduler connects to this service to invoke scheduled work item
/// callbacks. The service implementation is responsible for invoking the code that corresponds to
/// the scheduled work item identified by `work_id`.
/// Note: The intent of exposing this service is to expose it to the `WorkScheduler` service
/// provider (i.e., the framework) and no one else.
protocol Worker {
DoWork(WorkId work_id) -> () error fuchsia.component.Error;
/// Framework service: Administrative API for controlling parameters of the `WorkScheduler`
/// framework service. So long as there are work items with deadlines in the next `batch_period`,
/// the `WorkScheduler` will sleep for `batch_period`, then wake up and immediately dispatch a batch
/// of work items: all those with past deadlines. It will repeat this process until no work items
/// would be scheduled in the next `batch_period`, at which point it will go to sleep until the next
/// deadline. This strategy ensures that each work item is dispatched approximately within
/// `batch_period` of its deadline.
protocol WorkSchedulerControl {
/// Get the current period between `WorkScheduler` attempts to dispatch a batch of work.
/// `batch_period` is a non-negative 64-bit integer in the range [0, 2^63-1], representing a
/// number of nanoseconds between dispatching batches of work.
GetBatchPeriod() -> (zx.duration batch_period) error fuchsia.component.Error;
/// Set the current period between `WorkScheduler` attempts to batch and dispatch a batch of
/// work. `batch_period` is a non-negative 64-bit integer in the range [0, 2^63-1], representing
/// a number of nanoseconds between dispatching batches of work.
SetBatchPeriod(zx.duration batch_period) -> () error fuchsia.component.Error;