// 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;

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.
xunion Start {
    /// A non-negative delay to wait before scheduling work.
    zx.duration delay;
    /// A fixed point in time to start scheduling work, interpreted like `ZX_CLOCK_UTC`: number of
    /// wall clock nanoseconds since the Unix epoch (midnight on January 1 1970) in UTC.
    zx.time utc_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, inspecting, 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 Error;

    /// Get the current status of the scheduled work item identified by `work_id`. Note that
    /// canceled work items, and work items that do not repeat and has already run are not
    /// considered scheduled (and cannot be queried via this method).
    GetWorkById(WorkId work_id) -> (WorkStatus work_status) error Error;

    /// Cancel the scheduled work item specified by `work_id`.
    CancelWork(WorkId work_id) -> () error 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 Error;
};

/// Snapshot of the status of a scheduled work item.
table WorkStatus {
    /// Estimated next time to run this work item, interpreted like `ZX_CLOCK_UTC`: number of wall
    /// clock nanoseconds since the Unix epoch (midnight on January 1 1970) in UTC.
    1: zx.time next_run_utc_time;
    /// Period for rerunning work; unspecified when work is one-shot instead of repeating.
    2: zx.duration period;
};