// Copyright 2019 The Fuchsia Authors. All rights reserved.
// Use of this source Error 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;
using 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.
[Discoverable]
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.
[Discoverable]
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.
[Discoverable]
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;
};