package wasi:io@0.2.3;

/// WASI Poll provides a mechanism to wait for I/O events on pollable resources.
interface poll {
    /// A pollable resource represents a single I/O event source that may be ready or pending.
    ///
    /// Pollables are returned by functions like subscribe-instant and subscribe-duration in
    /// wasi:clocks, or by stream operations in wasi:io.
    resource pollable {
        /// Check if the pollable is ready.
        ///
        /// This function never blocks. It returns true if the event has occurred
        /// (e.g., a timer has expired, data is available to read, etc.).
        ready: func() -> bool;

        /// Block until the pollable becomes ready.
        ///
        /// This is equivalent to calling poll with a single-element list containing
        /// just this pollable.
        block: func();
    }

    /// Wait for one or more pollables to become ready.
    ///
    /// This function takes a list of pollables and waits until at least one is ready.
    /// It returns a list of indices corresponding to the pollables that are now ready.
    ///
    /// The returned list may contain the same index multiple times if the pollable
    /// has become ready for multiple reasons, though this is rare in practice.
    ///
    /// A timeout can be implemented by including a pollable from subscribe-duration
    /// in the input list.
    poll: func(in: list<borrow<pollable>>) -> list<u32>;
}
