Merge "Added the initial traits for bufferstreams." into main

    crate_name: "bufferstreams",

    srcs: ["src/lib.rs"],

    edition: "2021",

    vendor_available: true,

    host_supported: true,

    rlibs: [

        "libnativewindow_rs",

    ],

    min_sdk_version: "30",

}

//! libbufferstreams: Reactive Streams for Graphics Buffers

use nativewindow::*;

use std::sync::{Arc, Weak};

use std::time::Instant;

/// This function will print Hello World.

#[no_mangle]

pub extern "C" fn hello() -> bool {

    println!("Hello world.");

    true

}

/// BufferPublishers provide buffers to BufferSusbscribers. Depending on the

/// particular object in question, these could be allocated locally or provided

/// over IPC.

///

/// BufferPublishers are required to adhere to the following, based on the

/// reactive streams specification:

/// *   The total number of on_next´s signalled by a Publisher to a Subscriber

/// MUST be less than or equal to the total number of elements requested by that

/// Subscriber´s Subscription at all times.

/// *   A Publisher MAY signal fewer on_next than requested and terminate the

/// Subscription by calling on_complete or on_error.

/// *   on_subscribe, on_next, on_error and on_complete signaled to a Subscriber

/// MUST be signaled serially.

/// *   If a Publisher fails it MUST signal an on_error.

/// *   If a Publisher terminates successfully (finite stream) it MUST signal an

/// on_complete.

/// *   If a Publisher signals either on_error or on_complete on a Subscriber,

/// that Subscriber’s Subscription MUST be considered cancelled.

/// *   Once a terminal state has been signaled (on_error, on_complete) it is

/// REQUIRED that no further signals occur.

/// *   If a Subscription is cancelled its Subscriber MUST eventually stop being

///  signaled.

/// *  A Publisher MAY support multiple Subscribers and decides whether each

/// Subscription is unicast or multicast.

pub trait BufferPublisher {

    /// This function will create the subscription between the publisher and

    /// the subscriber.

    fn subscribe(&self, subscriber: Weak<dyn BufferSubscriber>);

}

/// BufferSubscribers can subscribe to BufferPublishers. They can request Frames

/// via the BufferSubscription they get from the publisher, then receive Frames

/// via on_next.

///

/// BufferSubcribers are required to adhere to the following, based on the

/// reactive streams specification:

/// *   The total number of on_next´s signalled by a Publisher to a Subscriber

/// MUST be less than or equal to the total number of elements requested by that

/// Subscriber´s Subscription at all times.

/// *   A Publisher MAY signal fewer on_next than requested and terminate the

/// Subscription by calling on_complete or on_error.

/// *   on_subscribe, on_next, on_error and on_complete signaled to a Subscriber

/// MUST be signaled serially.

/// *   If a Publisher fails it MUST signal an on_error.

/// *   If a Publisher terminates successfully (finite stream) it MUST signal an

/// on_complete.

/// *   If a Publisher signals either on_error or on_complete on a Subscriber,

/// that Subscriber’s Subscription MUST be considered cancelled.

/// *   Once a terminal state has been signaled (on_error, on_complete) it is

/// REQUIRED that no further signals occur.

/// *   If a Subscription is cancelled its Subscriber MUST eventually stop being

/// signaled.

/// *   Publisher.subscribe MAY be called as many times as wanted but MUST be

/// with a different Subscriber each time.

/// *   A Publisher MAY support multiple Subscribers and decides whether each

/// Subscription is unicast or multicast.

pub trait BufferSubscriber {

    /// This function will be called at the beginning of the subscription.

    fn on_subscribe(&self, subscription: Arc<dyn BufferSubscription>);

    /// This function will be called for buffer that comes in.

    fn on_next(&self, frame: Frame);

    /// This function will be called in case of an error.

    fn on_error(&self, error: BufferError);

    /// This function will be called on finite streams when done.

    fn on_complete(&self);

}

/// BufferSubscriptions serve as the bridge between BufferPublishers and

/// BufferSubscribers. BufferSubscribers receive a BufferSubscription when they

/// subscribe to a BufferPublisher via on_subscribe.

/// This object is to be used by the BufferSubscriber to cancel its subscription

/// or request more buffers.

///

/// BufferSubcriptions are required to adhere to the following, based on the

/// reactive streams specification:

/// *   Subscription.request and Subscription.cancel MUST only be called inside

/// of its Subscriber context.

/// *   The Subscription MUST allow the Subscriber to call Subscription.request

/// synchronously from within on_next or on_subscribe.

/// *   Subscription.request MUST place an upper bound on possible synchronous

/// recursion between Publisher and Subscriber.

/// *   Subscription.request SHOULD respect the responsivity of its caller by

/// returning in a timely manner.

/// *   Subscription.cancel MUST respect the responsivity of its caller by

/// returning in a timely manner, MUST be idempotent and MUST be thread-safe.

/// *   After the Subscription is cancelled, additional

/// Subscription.request(n: u64) MUST be NOPs.

/// *   After the Subscription is cancelled, additional Subscription.cancel()

/// MUST be NOPs.

/// *   While the Subscription is not cancelled, Subscription.request(n: u64)

/// MUST register the given number of additional elements to be produced to the

/// respective subscriber.

/// *   While the Subscription is not cancelled, Subscription.request(n: u64)

/// MUST signal on_error if the argument is <= 0. The cause message SHOULD

/// explain that non-positive request signals are illegal.

/// *  While the Subscription is not cancelled, Subscription.request(n: u64)

/// MAY synchronously call on_next on this (or other) subscriber(s).

/// *  While the Subscription is not cancelled, Subscription.request(n: u64)

/// MAY synchronously call on_complete or on_error on this (or other)

/// subscriber(s).

/// *  While the Subscription is not cancelled, Subscription.cancel() MUST

/// request the Publisher to eventually stop signaling its Subscriber. The

/// operation is NOT REQUIRED to affect the Subscription immediately.

/// *  While the Subscription is not cancelled, Subscription.cancel() MUST

/// request the Publisher to eventually drop any references to the corresponding

/// subscriber.

/// *  While the Subscription is not cancelled, calling Subscription.cancel MAY

/// cause the Publisher, if stateful, to transition into the shut-down state if

/// no other Subscription exists at this point.

/// *  Calling Subscription.cancel MUST return normally.

/// *  Calling Subscription.request MUST return normally.

pub trait BufferSubscription {

    /// request

    fn request(&self, n: u64);

    /// cancel

    fn cancel(&self);

}

/// Type used to describe errors produced by subscriptions.

type BufferError = Box<dyn std::error::Error + Send + Sync + 'static>;

/// Struct used to contain the buffer.

pub struct Frame {

    /// A handle to the C buffer interface.

    pub buffer: AHardwareBuffer,

    /// The time at which the buffer was dispatched.

    pub present_time: Instant,

    /// A fence used for reading/writing safely.

    pub fence: i32,

}