package theater:simple;

/// # Timing Interface
///
/// Provides time-related functions for actors to get the current time and control execution timing.
///
/// ## Purpose
///
/// The timing interface gives actors access to time information and timing control
/// within the Theater runtime. It allows actors to:
/// - Get the current time
/// - Pause execution for specific durations
/// - Delay execution until specific points in time
///
/// ## Example
///
/// ```rust
/// use ntwk::theater::timing;
///
/// async fn example() -> Result<(), String> {
///     // Get the current time
///     let now = timing::now();
///     println!("Current time: {}", now);
///     
///     // Sleep for 500 milliseconds
///     timing::sleep(500)?;
///     
///     // Wait until a specific future time
///     let five_seconds_later = now + 5000;
///     timing::deadline(five_seconds_later)?;
///     
///     Ok(())
/// }
/// ```
///
/// ## Security
///
/// The timing operations are managed by the Theater runtime, which may enforce:
/// - Rate limits on sleep operations to prevent resource exhaustion
/// - Maximum duration limits to prevent indefinite blocking
/// - Tracking and reporting of sleep patterns in the event chain
///
/// ## Implementation Notes
///
/// When actors call timing functions, the WebAssembly execution is suspended without
/// blocking the entire runtime. This allows the runtime to continue processing other
/// actors while an actor is waiting.
interface timing {
    /// # Get current time
    ///
    /// Returns the current time in milliseconds since the UNIX epoch (January 1, 1970 UTC).
    ///
    /// ## Returns
    ///
    /// The current timestamp in milliseconds
    ///
    /// ## Example
    ///
    /// ```rust
    /// use ntwk::theater::timing;
    ///
    /// // Get current timestamp
    /// let now = timing::now();
    ///
    /// // Convert to seconds
    /// let seconds_since_epoch = now / 1000;
    /// ```
    ///
    /// ## Implementation Notes
    ///
    /// The time value is consistent across the entire Theater runtime, ensuring that
    /// all actors have a synchronized view of time.
    now: func() -> u64;
    
    /// # Pause execution
    ///
    /// Pauses the execution of the actor for the specified number of milliseconds.
    ///
    /// ## Parameters
    ///
    /// * `duration` - Number of milliseconds to sleep
    ///
    /// ## Returns
    ///
    /// * `Ok(_)` - Sleep completed successfully
    /// * `Err(string)` - Error message if sleep was interrupted or not allowed
    ///
    /// ## Example
    ///
    /// ```rust
    /// use ntwk::theater::timing;
    ///
    /// // Sleep for 1 second
    /// timing::sleep(1000)?;
    ///
    /// // Sleep for 100ms
    /// timing::sleep(100)?;
    /// ```
    ///
    /// ## Security
    ///
    /// The runtime may enforce limits on how long an actor can sleep to prevent
    /// resource exhaustion or denial of service. Sleep operations are recorded
    /// in the actor's event chain.
    sleep: func(duration: u64) -> result<_, string>;
    
    /// # Wait until specific time
    ///
    /// Pauses execution until the specified timestamp is reached.
    ///
    /// ## Parameters
    ///
    /// * `timestamp` - Target time in milliseconds since UNIX epoch
    ///
    /// ## Returns
    ///
    /// * `Ok(_)` - Deadline was reached successfully
    /// * `Err(string)` - Error message if the wait was interrupted or not allowed
    ///
    /// ## Example
    ///
    /// ```rust
    /// use ntwk::theater::timing;
    ///
    /// // Wait until a specific time
    /// let target_time = 1672531200000; // Jan 1, 2023 00:00:00 UTC
    /// timing::deadline(target_time)?;
    ///
    /// // Wait until 10 seconds from now
    /// let now = timing::now();
    /// let ten_seconds_later = now + 10000;
    /// timing::deadline(ten_seconds_later)?;
    /// ```
    ///
    /// ## Implementation Notes
    ///
    /// - If the specified timestamp is in the past, the function returns immediately
    /// - The runtime may reject excessive deadline values that are too far in the future
    /// - Deadline operations are recorded in the actor's event chain
    deadline: func(timestamp: u64) -> result<_, string>;
}
