libs/bufferstreams/rust/src/lib.rs

// Copyright (C) 2023 The Android Open Source Project
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

//! libbufferstreams: Reactive Streams for Graphics Buffers

mod stream_config;

pub use stream_config::*;

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 {
    /// Returns the StreamConfig of buffers that publisher creates.
    fn get_publisher_stream_config(&self) -> StreamConfig;
    /// 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 {
    /// The StreamConfig of buffers that this subscriber expects.
    fn get_subscriber_stream_config(&self) -> StreamConfig;
    /// 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,
}