use core::{future::Future, marker::PhantomData, num::NonZeroUsize, pin::Pin, task::Poll};
use std::sync::Arc;
use smol_bytes::Utf8Bytes;
use super::{
Context, Effect, ItemId, NodeName, Spawn, Thread,
downstream::Sink,
feed::{FeedContext, FeedPolicy, Fixed, MemoryProbe, Unpressured},
lifecycle::{Failure, Lifecycle, LifecycleTap, Taps},
message::{Delivery, Item, ack_channel},
window::{Outbound, Owed},
};
use crate::{
Async, AsyncStreamOperator, Block, Fin, Skip, SkipReason, Stopper, StreamOperator, Yielded,
};
#[cfg(test)]
mod tests;
pub const DEFAULT_IN_FLIGHT: NonZeroUsize = NonZeroUsize::new(1).expect("1 is not zero");
pub const UNDIVIDABLE: &str = "undividable_output";
#[diagnostic::on_unimplemented(
message = "`{Self}` is not a STREAMING unit in the `{M}` mode",
label = "no `run` of this mode's shape",
note = "a streaming unit implements exactly ONE of `StreamOperator` (the blocking face, mode \
`Block`) and `AsyncStreamOperator` (the awaited face, mode `Async`), and implementing \
either IS implementing this trait's row for it",
note = "where a declaration is mounted, the mode is the one its own word selected and its \
`Declared::Mode` states: `stream` alone asks for `Block` and `stream, async` asks for \
`Async`, so a body whose face differs from its word is refused here",
note = "if `{Self}` wears the BUFFERED pair instead, it is mounted through `Blueprint::node` and \
`Wiring::resident` — this door is the streaming one, and the `stream` word is what sends \
a declaration to it"
)]
pub trait Streams<M> {
const SYNC: bool;
type In;
type Out: 'static;
type Error;
type Run;
}
impl<O> Streams<Block> for O
where
O: StreamOperator,
{
const SYNC: bool = true;
type In = <O as StreamOperator>::In;
type Out = <O as StreamOperator>::Out;
type Error = <O as StreamOperator>::Error;
type Run = flume::Receiver<Ended<Self, Block>>;
}
impl<O> Streams<Async> for O
where
O: AsyncStreamOperator,
{
const SYNC: bool = false;
type In = <O as AsyncStreamOperator>::In;
type Out = <O as AsyncStreamOperator>::Out;
type Error = <O as AsyncStreamOperator>::Error;
type Run = Pin<Box<dyn Future<Output = (Self, Result<Fin, <O as AsyncStreamOperator>::Error>)>>>;
}
pub type Ended<O, M> = (O, Result<Fin, <O as Streams<M>>::Error>);
type Park<O, M> = Pin<Box<dyn Future<Output = Option<<O as Streams<M>>::Out>>>>;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct Streamed {
given: usize,
projected: usize,
skipped: usize,
fin: Option<Fin>,
}
impl Streamed {
#[inline]
#[must_use]
pub const fn given(&self) -> usize {
self.given
}
#[inline]
#[must_use]
pub const fn projected(&self) -> usize {
self.projected
}
#[inline]
#[must_use]
pub const fn skipped(&self) -> usize {
self.skipped
}
#[inline]
#[must_use]
pub const fn fin(&self) -> Option<Fin> {
self.fin
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, derive_more::Display)]
#[display(
"this delivery's run ended without answering — its body panicked, or its thread was killed"
)]
pub struct Vanished;
impl core::error::Error for Vanished {}
#[derive(Clone)]
pub struct StreamOptions {
in_flight: NonZeroUsize,
feed: Arc<dyn FeedPolicy>,
probe: Arc<dyn MemoryProbe>,
}
impl StreamOptions {
#[inline]
#[must_use]
pub fn new() -> Self {
Self {
in_flight: DEFAULT_IN_FLIGHT,
feed: Arc::new(Fixed::default()),
probe: Arc::new(Unpressured),
}
}
#[inline]
#[must_use]
pub const fn in_flight(&self) -> NonZeroUsize {
self.in_flight
}
#[inline]
#[must_use]
pub fn with_in_flight(mut self, in_flight: NonZeroUsize) -> Self {
self.set_in_flight(in_flight);
self
}
#[inline]
pub fn set_in_flight(&mut self, in_flight: NonZeroUsize) -> &mut Self {
self.in_flight = in_flight;
self
}
#[inline]
#[must_use]
pub fn feed_policy(&self) -> &dyn FeedPolicy {
&*self.feed
}
#[inline]
#[must_use]
pub fn with_feed_policy(mut self, policy: Box<dyn FeedPolicy>) -> Self {
self.set_feed_policy(policy);
self
}
#[inline]
pub fn set_feed_policy(&mut self, policy: Box<dyn FeedPolicy>) -> &mut Self {
self.feed = Arc::from(policy);
self
}
#[inline]
#[must_use]
pub fn memory_probe(&self) -> &dyn MemoryProbe {
&*self.probe
}
#[inline]
#[must_use]
pub fn with_memory_probe(mut self, probe: Box<dyn MemoryProbe>) -> Self {
self.set_memory_probe(probe);
self
}
#[inline]
pub fn set_memory_probe(&mut self, probe: Box<dyn MemoryProbe>) -> &mut Self {
self.probe = Arc::from(probe);
self
}
}
impl Default for StreamOptions {
#[inline]
fn default() -> Self {
Self::new()
}
}
impl core::fmt::Debug for StreamOptions {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
f.debug_struct("StreamOptions")
.field("in_flight", &self.in_flight)
.finish_non_exhaustive()
}
}
struct Line<O, M>
where
O: Streams<M>,
{
yielded: Arc<Yielded<<O as Streams<M>>::Out>>,
run: <O as Streams<M>>::Run,
ended: Option<Ended<O, M>>,
stopper: Stopper,
owed: Owed<ItemId>,
info: Streamed,
}
impl<O, M> Line<O, M>
where
O: Streams<M>,
{
fn drained(&self) -> bool {
self.yielded.is_disconnected() && self.yielded.is_empty()
}
fn answered(&self) -> bool {
self.ended.is_some() && self.yielded.is_empty()
}
}
pub struct StreamLane<O, S, X = Thread, M = Block>
where
O: Streams<M>,
{
window: Context,
options: StreamOptions,
spawner: X,
downstream: S,
windows: Vec<Outbound<ItemId>>,
effect: Effect,
taps: Taps,
warm: Vec<O>,
live: Vec<Line<O, M>>,
minted: usize,
next_item: u64,
turn: usize,
mode: PhantomData<fn() -> M>,
}
impl<O, S, X, M> StreamLane<O, S, X, M>
where
O: Streams<M>,
{
#[must_use]
pub fn new(
ctx: Context,
options: StreamOptions,
instances: impl IntoIterator<Item = O>,
downstream: S,
spawner: X,
) -> Self {
Self {
window: ctx,
options,
spawner,
downstream,
windows: Vec::new(),
effect: Effect::Pure,
taps: Taps::new(),
warm: Vec::new(),
live: Vec::new(),
minted: 0,
next_item: 0,
turn: 0,
mode: PhantomData,
}
.warmed(instances)
}
fn warmed(mut self, instances: impl IntoIterator<Item = O>) -> Self {
self.warm.extend(instances);
self.minted = self.warm.len();
self
}
#[inline]
#[must_use]
pub fn name(&self) -> &NodeName {
self.window.node()
}
#[inline]
#[must_use]
pub const fn options(&self) -> &StreamOptions {
&self.options
}
#[inline]
#[must_use]
pub fn width(&self) -> usize {
self.minted.min(self.options.in_flight.get())
}
#[inline]
#[must_use]
pub fn in_flight(&self) -> usize {
self.live.len()
}
#[inline]
#[must_use]
pub fn idle(&self) -> usize {
self.warm.len()
}
#[inline]
#[must_use]
pub const fn downstream(&self) -> &S {
&self.downstream
}
#[inline]
#[must_use]
pub const fn effect(&self) -> Effect {
self.effect
}
#[inline]
#[must_use]
pub fn with_effect(mut self, effect: Effect) -> Self {
self.set_effect(effect);
self
}
#[inline]
pub fn set_effect(&mut self, effect: Effect) -> &mut Self {
self.effect = effect;
self
}
#[inline]
#[must_use]
pub fn with_taps(mut self, taps: Taps) -> Self {
self.set_taps(taps);
self
}
#[inline]
pub fn set_taps(&mut self, taps: Taps) -> &mut Self {
self.taps = taps;
self
}
pub fn stop(&self) {
for line in &self.live {
line.stopper.announce();
}
}
}
impl<O, S, X, M> StreamLane<O, S, X, M>
where
O: Streams<M>,
S: Sink<<O as Streams<M>>::Out>,
{
async fn project(&mut self, index: usize, items: Vec<<O as Streams<M>>::Out>) {
self.live[index].info.given += items.len();
let arity = self.downstream.arity();
while self.windows.len() < arity {
self.windows.push(Outbound::new());
}
if !self.downstream.connected().any() {
self.live[index].info.skipped += items.len();
return;
}
let mut batches: Vec<Vec<Item<<O as Streams<M>>::Out>>> =
core::iter::repeat_with(Vec::new).take(arity).collect();
let mut undividable = false;
for output in items {
let Some(last) = (0..arity)
.rev()
.find(|edge| self.downstream.carries(*edge, &output))
else {
self.live[index].info.skipped += 1;
continue;
};
let mut value = Some(output);
for (edge, batch) in batches.iter_mut().enumerate().take(last + 1) {
let held = value
.as_ref()
.expect("the value is taken only at the last edge");
if edge != last && !self.downstream.carries(edge, held) {
continue;
}
let copy = if edge == last {
value.take().expect("taken exactly once")
} else if let Some(copy) = self.downstream.duplicate(held) {
copy
} else {
undividable = true;
continue;
};
let id = ItemId::new(self.next_item);
self.next_item += 1;
batch.push(Item::new(id, copy));
}
self.live[index].info.projected += 1;
}
if undividable {
self.undividable();
}
for (edge, batch) in batches.into_iter().enumerate() {
if batch.is_empty() {
continue;
}
let ids: Vec<ItemId> = batch.iter().map(|item| *item.key()).collect();
let (ack, answers) = ack_channel();
if self.downstream.deliver(edge, batch, ack).await {
self.windows[edge].record(ids, answers);
} else {
self.hung_up();
}
}
}
fn hung_up(&self) {
let observation =
Lifecycle::<Streamed>::Skipped(Skip::new(SkipReason::ServiceInactive)).erase();
self.taps.observe(self.window.node(), &observation);
}
fn undividable(&self) {
let reason = SkipReason::custom(Utf8Bytes::from_static(UNDIVIDABLE));
let observation = Lifecycle::<Streamed>::Skipped(Skip::new(reason)).erase();
self.taps.observe(self.window.node(), &observation);
}
fn harvest(&mut self) {
let taps = &self.taps;
for window in &mut self.windows {
for answer in window.harvest().into_answers() {
taps.observe(answer.worker(), answer.observation());
}
}
}
fn settle(&mut self, mut line: Line<O, M>, ended: Result<Fin, Failure>) {
let lifecycle = match ended {
Ok(fin) => {
line.info.fin = Some(fin);
self.effect.reached(line.info)
}
Err(failure) => Lifecycle::Failed(failure),
};
self
.taps
.observe(self.window.node(), &lifecycle.clone().erase());
line.owed.settle(self.window.named().clone(), lifecycle);
}
}
impl<O, S, X> StreamLane<O, S, X, Block>
where
O: StreamOperator + Send + 'static,
<O as StreamOperator>::In: Send + 'static,
<O as StreamOperator>::Out: Send,
<O as StreamOperator>::Error: core::error::Error + Send + Sync + 'static,
S: Sink<<O as StreamOperator>::Out>,
X: Spawn,
{
pub async fn admit(
&mut self,
delivery: Delivery<<O as StreamOperator>::In>,
) -> Result<(), Delivery<<O as StreamOperator>::In>> {
while self.warm.is_empty() {
if !self.tend().await {
return Err(delivery);
}
}
let unit = self.warm.pop().expect("the loop above left one");
let (feed, yielded) = crate::feed(self.depth().get());
let (stopper, stop) = crate::shutdown_signal();
let ctx = self.window.reopened(stop);
let (tell, told) = flume::bounded(1);
let (payload, ack) = delivery.into_parts();
let owed = Owed::open(payload.keys().copied(), ack);
let handed = Delivery::in_custody(payload);
self.spawner.spawn(move || {
let mut unit = unit;
let ended = unit.run(&ctx, handed, feed);
let _ = tell.send((unit, ended));
});
self.live.push(Line {
yielded: Arc::new(yielded),
run: told,
ended: None,
stopper,
owed,
info: Streamed::default(),
});
Ok(())
}
pub async fn tend(&mut self) -> bool {
if self.live.is_empty() {
return false;
}
if !self.pass().await {
if let Some((index, item)) = self.woken().await {
self.project(index, vec![item]).await;
}
self.pass().await;
}
true
}
pub async fn drain(&mut self) {
while self.tend().await {}
}
async fn pass(&mut self) -> bool {
let mut moved = false;
for index in 0..self.live.len() {
let taken: Vec<_> = self.live[index].yielded.drain().collect();
if !taken.is_empty() {
moved = true;
self.project(index, taken).await;
}
}
let mut index = 0;
while index < self.live.len() {
if !self.live[index].drained() {
index += 1;
continue;
}
moved = true;
let line = self.live.remove(index);
match line.run.recv_async().await {
Ok((unit, ended)) => {
self.warm.push(unit);
self.settle(line, ended.map_err(Failure::new));
}
Err(_) => {
self.minted -= 1;
self.settle(line, Err(Failure::new(Vanished)));
}
}
}
self.harvest();
moved
}
async fn woken(&mut self) -> Option<(usize, <O as StreamOperator>::Out)> {
let (mut arms, waiting) = self.arms();
if !waiting {
return None;
}
let turn = self.turn;
let (index, item) = core::future::poll_fn(|cx| {
let count = arms.len();
if count == 0 {
return Poll::Ready((0, None));
}
for step in 0..count {
let index = (turn + step) % count;
if let Poll::Ready(item) = arms[index].as_mut().poll(cx) {
return Poll::Ready((index, item));
}
}
Poll::Pending
})
.await;
self.turn = index + 1;
item.map(|item| (index, item))
}
}
impl<O, S, X> StreamLane<O, S, X, Async>
where
O: AsyncStreamOperator + 'static,
<O as AsyncStreamOperator>::In: 'static,
<O as AsyncStreamOperator>::Error: core::error::Error + Send + Sync + 'static,
S: Sink<<O as AsyncStreamOperator>::Out>,
{
pub async fn admit(
&mut self,
delivery: Delivery<<O as AsyncStreamOperator>::In>,
) -> Result<(), Delivery<<O as AsyncStreamOperator>::In>> {
while self.warm.is_empty() {
if !self.tend().await {
return Err(delivery);
}
}
let unit = self.warm.pop().expect("the loop above left one");
let (feed, yielded) = crate::feed(self.depth().get());
let (stopper, stop) = crate::shutdown_signal();
let ctx = self.window.reopened(stop);
let (payload, ack) = delivery.into_parts();
let owed = Owed::open(payload.keys().copied(), ack);
let handed = Delivery::in_custody(payload);
let run: <O as Streams<Async>>::Run = Box::pin(async move {
let mut unit = unit;
let ended = unit.run(&ctx, handed, feed).await;
(unit, ended)
});
self.live.push(Line {
yielded: Arc::new(yielded),
run,
ended: None,
stopper,
owed,
info: Streamed::default(),
});
Ok(())
}
pub async fn tend(&mut self) -> bool {
if self.live.is_empty() {
return false;
}
if !self.pass().await {
if let Some((index, item)) = self.woken().await {
self.project(index, vec![item]).await;
}
self.pass().await;
}
true
}
pub async fn drain(&mut self) {
while self.tend().await {}
}
async fn pass(&mut self) -> bool {
let mut moved = false;
for index in 0..self.live.len() {
let taken: Vec<_> = self.live[index].yielded.drain().collect();
if !taken.is_empty() {
moved = true;
self.project(index, taken).await;
}
}
let mut index = 0;
while index < self.live.len() {
if !self.live[index].answered() {
index += 1;
continue;
}
moved = true;
let mut line = self.live.remove(index);
let (unit, ended) = line
.ended
.take()
.expect("`answered` is exactly the question of whether this is `Some`");
self.warm.push(unit);
self.settle(line, ended.map_err(Failure::new));
}
self.harvest();
moved
}
async fn woken(&mut self) -> Option<(usize, <O as AsyncStreamOperator>::Out)> {
let (mut arms, _waiting) = self.arms();
let lines = &mut self.live;
let turn = self.turn;
let (index, item) = core::future::poll_fn(|cx| {
let count = arms.len();
if count == 0 {
return Poll::Ready((0, None));
}
for step in 0..count {
let index = (turn + step) % count;
if lines[index].ended.is_none()
&& let Poll::Ready(answered) = lines[index].run.as_mut().poll(cx)
{
lines[index].ended = Some(answered);
return Poll::Ready((index, None));
}
if let Poll::Ready(item) = arms[index].as_mut().poll(cx) {
return Poll::Ready((index, item));
}
}
Poll::Pending
})
.await;
self.turn = index + 1;
item.map(|item| (index, item))
}
}
impl<O, S, X, M> StreamLane<O, S, X, M>
where
O: Streams<M>,
{
fn arms(&self) -> (Vec<Park<O, M>>, bool) {
let mut waiting = false;
let arms = self
.live
.iter()
.map(|line| {
if line.drained() {
return Box::pin(core::future::pending()) as Park<O, M>;
}
waiting = true;
let yielded = Arc::clone(&line.yielded);
Box::pin(async move { yielded.take_async().await }) as Park<O, M>
})
.collect();
(arms, waiting)
}
fn depth(&self) -> NonZeroUsize {
let width = NonZeroUsize::new(self.width()).unwrap_or(NonZeroUsize::MIN);
let ctx = FeedContext::new(self.live.len(), width, self.options.memory_probe());
self.options.feed_policy().capacity(&ctx)
}
}
impl<O, S, X, M> core::fmt::Debug for StreamLane<O, S, X, M>
where
O: Streams<M>,
{
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
f.debug_struct("StreamLane")
.field("node", &self.window.node().as_str())
.field("width", &self.width())
.field("in_flight", &self.live.len())
.field("idle", &self.warm.len())
.finish_non_exhaustive()
}
}