//! # MultiPlayer Code Editing
//!
//! This is the core library of the codemp project.
//!
//! ## Structure
//! The main entrypoint is the [client::Client] object, that maintains a connection and can 
//! be used to join workspaces or attach to buffers.
//! 
//! Some actions will return structs implementing the [Controller] trait. These can be polled 
//! for new stream events, which will be returned in order. Blocking and callback variants are also 
//! implemented. The [Controller] can also be used to send new events to the server.
//!
//! ## Features
//! * `proto` : include GRCP protocol definitions under [proto] (default)
//! * `global`: provide a lazy_static global INSTANCE in [instance::global]
//! * `sync`  : wraps the [instance::a_sync::Instance] holder into a sync variant: [instance::sync::Instance]
//! 


/// cursor related types and controller
pub mod cursor;

/// buffer operations, factory, controller and types
pub mod buffer;

/// crate error types and helpers
pub mod errors;

/// underlying client session manager
pub mod client;

/// client wrapper to handle memory persistence
pub mod instance;

/// all-in-one imports : `use codemp::prelude::*;`
pub mod prelude;

/// underlying OperationalTransform library used, re-exported
pub use operational_transform as ot;

pub use client::Client;

#[cfg(feature = "sync")]      pub use instance::sync::Instance;
#[cfg(not(feature = "sync"))] pub use instance::a_sync::Instance;

/// protocol types and services auto-generated by grpc
#[cfg(feature = "proto")]
#[allow(non_snake_case)]
pub mod proto {
	tonic::include_proto!("codemp.buffer");
	tonic::include_proto!("codemp.cursor");
}

pub use errors::Error;
pub use errors::Result;

use std::sync::Arc;
use tokio::runtime::Runtime;

#[tonic::async_trait] // TODO move this somewhere?
pub(crate) trait ControllerWorker<T : Sized + Send + Sync> {
	type Controller : Controller<T>;
	type Tx;
	type Rx;

	fn subscribe(&self) -> Self::Controller;
	async fn work(self, tx: Self::Tx, rx: Self::Rx);
}

/// async and threadsafe handle to a generic bidirectional stream
///
/// this generic trait is implemented by actors managing stream procedures.
/// events can be enqueued for dispatching without blocking ([Controller:send]), and an async blocking 
/// api ([Controller::recv]) is provided to wait for server events. Additional sync blocking
/// ([Controller::blocking_recv]) and callback-based ([Controller::callback]) are implemented.
#[tonic::async_trait]
pub trait Controller<T : Sized + Send + Sync> : Sized + Send + Sync {
	/// type of upstream values, used in [Self::send]
	type Input;

	/// enqueue a new value to be sent
	fn send(&self, x: Self::Input) -> Result<()>;

	/// get next value from stream, blocking until one is available
	async fn recv(&self) -> Result<T>;

	/// sync variant of [Self::recv], blocking invoking thread
	fn blocking_recv(&self, rt: &Runtime) -> Result<T> {
		rt.block_on(self.recv())
	}

	/// register a callback to be called for each received stream value
	///
	/// this will spawn a new task on given runtime invoking [Self::recv] in loop and calling given
	/// callback for each received value. a stop channel should be provided, and first value sent
	/// into it will stop the worker loop.
	///
	/// note: creating a callback handler will hold an Arc reference to the given controller,
	/// preventing it from being dropped (and likely disconnecting). using the stop channel is
	/// important for proper cleanup
	fn callback<F>(
		self: Arc<Self>,
		rt: &tokio::runtime::Runtime,
		mut stop: tokio::sync::mpsc::UnboundedReceiver<()>,
		mut cb: F
	) where
		Self : 'static,
		F : FnMut(T) + Sync + Send + 'static
	{
		rt.spawn(async move {
			loop {
				tokio::select! {
					Ok(data) = self.recv() => cb(data),
					Some(()) = stop.recv() => break,
					else => break,
				}
			}
		});
	}
}