SourceOps

Attaches the given Sink to this Source, meaning elements that pass through will also be sent to the Sink. If sending to the output channel or the other Sink blocks, no elements will be processed until both channels can receive elements again. The source elements are first sent to the output channel and then, only if the sent is successful, to the other Sink.

If this source is failed, then failure is passed to the returned channel and the other Sink. If the other sink fails or closes, then failure or closure is passed to the returned channel as well (contrary to alsoToTap where it's ignored).

Value parameters

other: The Sink to which elements from this source will be sent.

Attributes

Returns

A source that emits input elements.

See also

alsoToTap for a version that drops elements when the other Sink is not available for receive.

Example

 import ox.*
 import ox.channels.Source
 supervised {
   val c = Channel.withCapacity[Int](10)
   Source.fromValues(1, 2, 3).alsoTo(c).toList // List(1, 2, 3)
   c.toList // List(1, 2, 3)
 }

Attaches the given Sink to this Source, meaning elements that pass through will also be sent to the Sink. If the other Sink is not available for receive, the elements are still sent to returned channel, but not to the other Sink, meaning that some elements may be dropped.

If this source is failed, then failure is passed to the returned channel and the other Sink. If the other sink fails or closes, then failure or closure is ignored and it doesn't affect the resulting source (contrary to alsoTo where it's propagated).

Value parameters

other: The Sink to which elements from this source will be sent.

Attributes

Returns

A source that emits input elements.

See also

alsoTo for a version that ensures that elements are sent to both the output and the other Sink.

Example

 import ox.*
 import ox.channels.Source
 supervised {
   val c = Channel.withCapacity[Int](10)
   Source.fromValues(1, 2, 3).alsoToTap(c).toList // List(1, 2, 3)
   c.toList // List(1, 2, 3) but not guaranteed
 }

Creates a view of this source, where the results of receive will be transformed on the consumer's thread using the given function f. If the function is not defined at an element, the element will be skipped.

The same logic applies to receive clauses created using this source, which can be used in select.

Value parameters

f: The collecting function. Results should not be null.

Attributes

Returns: A source which is a view of this source, with the collecting function applied.

Concatenates this source with the other source. The resulting source will emit elements from this source first, and then from the other source.

Value parameters

other: The source to be appended to this source.

Attributes

Example

 import ox.*
 import ox.channels.Source
 supervised {
   Source.fromValues(1, 2).concat(Source.fromValues(3, 4)).toList // List(1, 2, 3, 4)
 }

Drops n elements from this source and forwards subsequent elements to the returned channel.

Value parameters

n: Number of elements to be dropped.

Attributes

Example

 import ox.*
 import ox.channels.Source
 supervised {
   Source.empty[Int].drop(1).toList          // List()
   Source.fromValues(1, 2, 3).drop(1).toList // List(2 ,3)
   Source.fromValues(1).drop(2).toList       // List()
 }

Lazily-evaluated filter: Creates a view of this source, where the results of receive will be filtered on the consumer's thread using the given predicate p. For an eager, asynchronous version, see filter.

The same logic applies to receive clauses created using this source, which can be used in select.

Value parameters

f: The predicate to use for filtering.

Attributes

Returns: A source which is a view of this source, with the filtering function applied.

Chunks up the elements into groups of the specified size. The last group may be smaller due to channel being closed. If this source is failed then failure is passed to the returned channel.

Value parameters

n: The number of elements in a group.

Attributes

Returns

A source that emits grouped elements.

Example

 import ox.*
 import ox.channels.Source
 supervised {
   Source.fromValues(1, 2, 3, 4, 5, 6, 7).grouped(3).toList // List(Seq(1, 2, 3), Seq(4, 5, 6), Seq(7))
 }

Chunks up the elements into groups that have a cumulative weight greater or equal to the minWeight. The last group may be smaller due to channel being closed. If this source is failed then failure is passed to the returned channel.

Upstream error or exception thrown by costFn will result in this Source failing with that error.

Value parameters

costFn: The function that calculates the weight of an element.
minWeight: The minimum cumulative weight of elements in a group.

Attributes

Returns

A source that emits grouped elements.

Example

 import ox.*
 import ox.channels.Source
 supervised {
   Source.fromValues(1, 2, 3, 4, 5, 6, 7).groupedWeighted(10)(n => n * 2).toList // List(Seq(1, 2, 3), Seq(4, 5), Seq(6), Seq(7))
 }

Chunks up the elements into groups received within a time window or limited by the cumulative weight being greater or equal to the minWeight, whatever happens first. The timeout is reset after a group is emitted. If timeout expires and the buffer is empty, nothing is emitted. As soon as a new element is received, the source will emit it as a single-element group and reset the timer.

Upstream error or exception thrown by costFn will result in this Source failing with that error.

Value parameters

costFn: The function that calculates the weight of an element.
duration: The time window in which the elements are grouped.
minWeight: The minimum cumulative weight of elements in a group if no timeout happens.

Attributes

Returns

A source that emits grouped elements.

Example

 import ox.*
 import ox.channels.Source
 supervised {
   val c = StageCapacity.newChannel[Int]
   fork {
     c.send(1)
     c.send(2)
     sleep(200.millis)
     c.send(3)
     c.send(4)
     c.send(5)
     c.send(6)
     c.done()
   }
   c.groupedWeightedWithin(10, 100.millis)(n => n * 2).toList // List(Seq(1, 2), Seq(3, 4), Seq(5), Seq(6))
 }

Chunks up the elements into groups received within a time window or limited by the specified number of elements, whatever happens first. The timeout is reset after a group is emitted. If timeout expires and the buffer is empty, nothing is emitted. As soon as a new element is received, the source will emit it as a single-element group and reset the timer.

If this source is failed then failure is passed to the returned channel.

Value parameters

duration: The time window in which the elements are grouped.
n: The maximum number of elements in a group.

Attributes

Returns

A source that emits grouped elements.

Example

 import ox.*
 import ox.channels.Source
 supervised {
   val c = StageCapacity.newChannel[Int]
   fork {
     c.send(1)
     c.send(2)
     sleep(200.millis)
     c.send(3)
     c.send(4)
     c.send(5)
     c.send(6)
     c.done()
   }
   c.groupedWithin(3, 100.millis).toList // List(Seq(1, 2), Seq(3, 4, 5), Seq(6))
 }

Returns the first element from this source wrapped in Some or None when this source is empty. Note that headOption is not an idempotent operation on source as it receives elements from it.

Attributes

Returns

A Some(first element) if source is not empty or None otherwise.

Throws

ChannelClosedException.Error

When receiving an element from this source fails.

Example

 import ox.*
 import ox.channels.Source
 supervised {
   Source.empty[Int].headOption()  // None
   val s = Source.fromValues(1, 2)
   s.headOption()                  // Some(1)
   s.headOption()                  // Some(2)
 }

Sends a given number of elements (determined byc segmentSize) from this source to the returned channel, then sends the same number of elements from the other source and repeats. The order of elements in both sources is preserved.

If one of the sources is done before the other, the behavior depends on the eagerCancel flag. When set to true, the returned channel is completed immediately, otherwise the remaining elements from the other source are sent to the returned channel.

Must be run within a scope, since a child fork is created which receives from both sources and sends to the resulting channel.

Value parameters

eagerComplete: If true, the returned channel is completed as soon as either of the sources completes. If false, the remaining elements of the non-completed source are sent downstream.
other: The source whose elements will be interleaved with the elements of this source.
segmentSize: The number of elements sent from each source before switching to the other one. Default is 1.

Attributes

Returns

A source to which the interleaved elements from both sources would be sent.

Example

 scala>
 import ox.*
 import ox.channels.Source
 supervised {
   val s1 = Source.fromValues(1, 2, 3, 4, 5, 6, 7)
   val s2 = Source.fromValues(10, 20, 30, 40)
   s1.interleave(s2, segmentSize = 2).toList
 }
 scala> val res0: List[Int] = List(1, 2, 10, 20, 3, 4, 30, 40, 5, 6, 7)

Intersperses this source with provided element and forwards it to the returned channel.

Value parameters

inject: An element to be injected between the stream elements.

Attributes

Returns

A source, onto which elements will be injected.

Example

 import ox.*
 import ox.channels.Source
 supervised {
   Source.empty[String].intersperse(", ").toList            // List()
   Source.fromValues("foo").intersperse(", ").toList        // List(foo)
   Source.fromValues("foo", "bar").intersperse(", ").toList // List(foo, ", ", bar)
 }

Intersperses this source with start, end and provided elements and forwards it to the returned channel.

Value parameters

end: An element to be appended to the end of the stream.
inject: An element to be injected between the stream elements.
start: An element to be prepended to the stream.

Attributes

Returns

A source, onto which elements will be injected.

Example

 import ox.*
 import ox.channels.Source
 supervised {
   Source.empty[String].intersperse("[", ", ", "]").toList            // List([, ])
   Source.fromValues("foo").intersperse("[", ", ", "]").toList        // List([, foo, ])
   Source.fromValues("foo", "bar").intersperse("[", ", ", "]").toList // List([, foo, ", ", bar, ])
 }

Applies the given mapping function f to each element received from this source, and sends the results to the returned channel.

Errors from this channel are propagated to the returned channel. Any exceptions that occur when invoking f are propagated as errors to the returned channel as well.

Must be run within a scope, as a child fork is created, which receives from this source and sends the mapped values to the resulting one.

For a lazily-evaluated version, see mapAsView.

Value parameters

f: The mapping function.

Attributes

Returns: A source, onto which results of the mapping function will be sent.

Lazily-evaluated map: creates a view of this source, where the results of receive will be transformed on the consumer's thread using the given function f. For an eager, asynchronous version, see map.

The same logic applies to receive clauses created using this source, which can be used in select.

Value parameters

f: The mapping function. Results should not be null.

Attributes

Returns: A source which is a view of this source, with the mapping function applied.

Applies the given mapping function f, to each element received from this source, transforming it into an Iterable of results, then sends the results one by one to the returned channel. Can be used to unfold incoming sequences of elements into single elements.

Value parameters

f: A function that transforms the element from this source into a pair of the next state into an scala.collection.IterableOnce of results which are sent one by one to the returned channel. If the result of f is empty, nothing is sent to the returned channel.

Attributes

Returns

A source to which the results of applying f to the elements from this source would be sent.

Example

 scala>
 import ox.*
 import ox.channels.Source
 supervised {
   val s = Source.fromValues(List(1, 2, 3), List(4, 5, 6), List(7, 8, 9))
   s.mapConcat(identity)
 }
 scala> val res0: List[Int] = List(1, 2, 3, 4, 5, 6, 7, 8, 9)

Applies the given mapping function f to each element received from this source, and sends the results to the returned channel. At most parallelism invocations of f are run in parallel.

The mapped results are sent to the returned channel in the same order, in which inputs are received from this source. In other words, ordering is preserved.

Errors from this channel are propagated to the returned channel. Any exceptions that occur when invoking f are propagated as errors to the returned channel as well, and result in interrupting any mappings that are in progress.

Must be run within a scope, as child forks are created, which receive from this source, send to the resulting one, and run the mappings.

Value parameters

f: The mapping function.
parallelism: An upper bound on the number of forks that run in parallel. Each fork runs the function f on a single element of the source.

Attributes

Returns: A source, onto which results of the mapping function will be sent.

Applies the given mapping function f, using additional state, to each element received from this source, and sends the results to the returned channel. Optionally sends an additional element, possibly based on the final state, to the returned channel once this source is done.

The initializeState function is called once when statefulMap is called.

The onComplete function is called once when this source is done. If it returns a non-empty value, the value will be sent to the returned channel, while an empty value will be ignored.

Value parameters

f: A function that transforms the element from this source and the state into a pair of the next state and the result which is sent sent to the returned channel.
initializeState: A function that initializes the state.
onComplete: A function that transforms the final state into an optional element sent to the returned channel. By default the final state is ignored.

Attributes

Returns

A source to which the results of applying f to the elements from this source would be sent.

Example

 scala>
 import ox.*
 import ox.channels.Source
 supervised {
   val s = Source.fromValues(1, 2, 3, 4, 5)
   s.mapStateful(() => 0)((sum, element) => (sum + element, sum), Some.apply)
 }
 scala> val res0: List[Int] = List(0, 1, 3, 6, 10, 15)

Applies the given mapping function f, using additional state, to each element received from this source, and sends the results one by one to the returned channel. Optionally sends an additional element, possibly based on the final state, to the returned channel once this source is done.

The initializeState function is called once when statefulMap is called.

The onComplete function is called once when this source is done. If it returns a non-empty value, the value will be sent to the returned channel, while an empty value will be ignored.

Value parameters

f: A function that transforms the element from this source and the state into a pair of the next state and a scala.collection.IterableOnce of results which are sent one by one to the returned channel. If the result of f is empty, nothing is sent to the returned channel.
initializeState: A function that initializes the state.
onComplete: A function that transforms the final state into an optional element sent to the returned channel. By default the final state is ignored.

Attributes

Returns

A source to which the results of applying f to the elements from this source would be sent.

Example

 scala>
 import ox.*
 import ox.channels.Source
 supervised {
   val s = Source.fromValues(1, 2, 2, 3, 2, 4, 3, 1, 5)
   // deduplicate the values
   s.mapStatefulConcat(() => Set.empty[Int])((s, e) => (s + e, Option.unless(s.contains(e))(e)))
 }
 scala> val res0: List[Int] = List(1, 2, 3, 4, 5)

If this source has no elements then elements from an alternative source are emitted to the returned channel. If this source is failed then failure is passed to the returned channel.

Value parameters

alternative: An alternative source of elements used when this source is empty.

Attributes

Returns

A source that emits either elements from this source or from alternative (when this source is empty).

Example

 import ox.*
 import ox.channels.Source
 supervised {
   Source.fromValues(1).orElse(Source.fromValues(2, 3)).toList // List(1)
   Source.empty.orElse(Source.fromValues(2, 3)).toList         // List(2, 3)
 }

Prepends other source to this source. The resulting source will emit elements from other source first, and then from the this source.

Value parameters

other: The source to be prepended to this source.

Attributes

Example

 import ox.*
 import ox.channels.Source
 supervised {
   Source.fromValues(1, 2).prepend(Source.fromValues(3, 4)).toList // List(3, 4, 1, 2)
 }

Creates sliding windows of elements from this source. The window slides by step elements. The last window may be smaller due to channel being closed.

If this source is failed then failure is passed to the returned channel.

Value parameters

n: The number of elements in a window.
step: The number of elements the window slides by.

Attributes

Returns

A source that emits grouped elements.

Example

 import ox.*
 import ox.channels.Source
 supervised {
   Source.fromValues(1, 2, 3, 4, 5, 6).sliding(3, 2).toList // List(Seq(1, 2, 3), Seq(3, 4, 5), Seq(5, 6))
 }

Transform the source so that it returns elements as long as predicate f is satisfied (returns true). If includeFirstFailing is true, the returned source will additionally return the first element that failed the predicate. After that, the source will complete as Done.

Value parameters

f: A predicate function called on incoming elements. If it throws an exception, the result Source will be failed with that exception.
includeFirstFailing: Whether the source should also emit the first element that failed the predicate (false by default).

Attributes

Example

 import ox.*
 import ox.channels.Source
 supervised {
   Source.empty[Int].takeWhile(_ > 3).toList          // List()
   Source.fromValues(1, 2, 3).takeWhile(_ < 3).toList // List(1, 2)
   Source.fromValues(1, 2, 3, 4).takeWhile(_ < 3, includeFirstFailing = true).toList // List(1, 2, 3)
   Source.fromValues(3, 2, 1).takeWhile(_ < 3).toList // List()
 }

Applies the given consumer function f to each element received from this source.

Errors from this channel are propagated to the returned channel. Any exceptions that occur when invoking f are propagated as errors to the returned channel as well.

Must be run within a scope, as a child fork is created, which receives from this source and sends the mapped values to the resulting one.

Useful for side-effects without result values, like logging and debugging. For a lazily-evaluated version, see tapAsView.

Value parameters

f: The consumer function.

Attributes

Returns: A source, which the elements from the input source are passed to.

Lazily-evaluated tap: creates a view of this source, where the results of receive will be applied to the given function f on the consumer's thread. Useful for side-effects without result values, like logging and debugging. For an eager, asynchronous version, see tap.

The same logic applies to receive clauses created using this source, which can be used in select.

Value parameters

f: The consumer function.

Attributes

Returns: A source which is a view of this source, with the consumer function applied.

Sends elements to the returned channel limiting the throughput to specific number of elements (evenly spaced) per time unit. Note that the element's receive() time is included in the resulting throughput. For instance having throttle(1, 1.second) and receive() taking Xms means that resulting channel will receive elements every 1s + Xms time. Throttling is not applied to the empty source.

Value parameters

elements: Number of elements to be emitted. Must be greater than 0.
per: Per time unit. Must be greater or equal to 1 ms.

Attributes

Returns

A source that emits at most elements per time unit.

Example

 import ox.*
 import ox.channels.Source
 import scala.concurrent.duration.*
 supervised {
   Source.empty[Int].throttle(1, 1.second).toList       // List() returned without throttling
   Source.fromValues(1, 2).throttle(1, 1.second).toList // List(1, 2) returned after 2 seconds
 }

Combines elements from this and other sources into tuples handling early completion of either source with defaults.

Value parameters

other: A source of elements to be combined with.
otherDefault: A default element to be used in the result tuple when the current source is longer.
thisDefault: A default element to be used in the result tuple when the other source is longer.

Attributes

Example

 import ox.*
 import ox.channels.Source
 supervised {
   Source.empty[Int].zipAll(Source.empty[String], -1, "foo").toList      // List()
   Source.empty[Int].zipAll(Source.fromValues("a"), -1, "foo").toList    // List((-1, "a"))
   Source.fromValues(1).zipAll(Source.empty[String], -1, "foo").toList   // List((1, "foo"))
   Source.fromValues(1).zipAll(Source.fromValues("a"), -1, "foo").toList // List((1, "a"))
 }

SourceOps

Attributes

Members list

Value members

Concrete methods

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes