Gears
API
Generated with
Gears/gears.async

gears.async

package gears.async

Asynchronous programming support with direct-style Scala.

Attributes

See also

gears.async.Async for an introduction to the Async context and how to create them.

gears.async.Future for a simple interface to spawn concurrent computations.

gears.async.Channel for a simple inter-future communication primitive.

Members list

Packages

package gears.async.default
package gears.async.listeners

Type members

Classlikes

trait Async(using val support: AsyncSupport, val scheduler: support.Scheduler)

The async context: provides the capability to asynchronously await for Sources, and defines a scope for structured concurrency through a CompletionGroup.

The async context: provides the capability to asynchronously await for Sources, and defines a scope for structured concurrency through a CompletionGroup.

As both a context and a capability, the idiomatic way of using Async is to be implicitly passed around functions, as an using parameter:

def function()(using Async): T = ???

It is not recommended to store Async in a class field, since it complicates scoping rules.

Value parameters

scheduler

An implementation of a scheduler, for scheduling computation as they are spawned or resumed. See Scheduler.

support

An implementation of the underlying asynchronous operations (suspend and resume). See AsyncSupport.

Attributes

See also

Async.blocking for a way to construct an Async instance.

Async.group and Future.apply for Async-subscoping operations.

Companion
object
Supertypes
class Object
trait Matchable
class Any
opaque object Async

Attributes

Companion
trait
Supertypes
class Object
trait Matchable
class Any
Self type
Async.type
trait AsyncOperations

Defines fundamental operations that require the support of the scheduler. This is commonly provided alongside with the given implementation of Scheduler.

Defines fundamental operations that require the support of the scheduler. This is commonly provided alongside with the given implementation of Scheduler.

Attributes

See also

Scheduler for the definition of the scheduler itself.

Companion
object
Supertypes
class Object
trait Matchable
class Any
Known subtypes
object AsyncOperations

Attributes

Companion
trait
Supertypes
class Object
trait Matchable
class Any
Self type
trait AsyncSupport extends SuspendSupport

Extends SuspendSupport with "asynchronous" boundary/resume functions, in the presence of a Scheduler

Extends SuspendSupport with "asynchronous" boundary/resume functions, in the presence of a Scheduler

Attributes

Companion
object
Supertypes
class Object
trait Matchable
class Any
Known subtypes
object AsyncSupport

Attributes

Companion
trait
Supertypes
class Object
trait Matchable
class Any
Self type
trait BufferedChannel[T] extends Channel[T]

Buffered channels are channels with an internal value buffer (represented internally as an array with positive size). They have the following semantics:

Buffered channels are channels with an internal value buffer (represented internally as an array with positive size). They have the following semantics:

  • send, when the buffer is not full, appends the value to the buffer and success immediately.
  • send, when the buffer is full, suspends until some buffer slot is freed and assigned to this sender.

See BufferedChannel$.apply for creation of buffered channels.

Attributes

Companion
object
Supertypes
trait Channel[T]
trait Closeable
trait AutoCloseable
trait ReadableChannel[T]
trait SendableChannel[T]
class Object
trait Matchable
class Any
Show all
Known subtypes
trait UnboundedChannel[T]
object BufferedChannel

Attributes

Companion
trait
Supertypes
class Object
trait Matchable
class Any
Self type
trait Cancellable

A trait for cancellable entities that can be grouped.

A trait for cancellable entities that can be grouped.

Attributes

Companion
object
Supertypes
class Object
trait Matchable
class Any
Known subtypes
trait Tracking
object Unlinked
trait Future[T]
trait Promise[T]
class Timer
Show all
object Cancellable

Attributes

Companion
trait
Supertypes
class Object
trait Matchable
class Any
Self type
trait Channel[T] extends SendableChannel[T], ReadableChannel[T], Closeable

A generic channel that can be sent to, received from and closed.

A generic channel that can be sent to, received from and closed.

Attributes

See also

SyncChannel, BufferedChannel and UnboundedChannel for channel implementations.

Example 
// send from one Future, read from multiple
val ch = SyncChannel[Int]()
val sender = Future:
 for i <- 1 to 20 do
   ch.send(i)
   ch.close()
val receivers = (1 to 5).map: n =>
 Future:
   boundary:
     while true:
       ch.read() match
         case Right(k) => println(s"Receiver $n got: $k")
         case Left(_) => boundary.break()
receivers.awaitAll
Companion
object
Supertypes
trait Closeable
trait AutoCloseable
trait ReadableChannel[T]
trait SendableChannel[T]
class Object
trait Matchable
class Any
Show all
Known subtypes
trait BufferedChannel[T]
trait UnboundedChannel[T]
trait SyncChannel[T]
object Channel

Attributes

Companion
trait
Supertypes
class Object
trait Matchable
class Any
Self type
Channel.type
class ChannelClosedException extends Exception

The exception raised by send (or UnboundedChannel.sendImmediately) on a closed Channel.

The exception raised by send (or UnboundedChannel.sendImmediately) on a closed Channel.

It is also returned wrapped in Failure when reading form a closed channel. ChannelMultiplexer sends Failure(ChannelClosedException) to all subscribers when it receives a close() signal.

Attributes

Supertypes
class Exception
class Throwable
trait Serializable
class Object
trait Matchable
class Any
Show all
trait ChannelMultiplexer[T] extends Closeable

Channel multiplexer is an object where one can register publisher and subscriber channels. When it is run, it continuously races the set of publishers and once it reads a value, it sends a copy to each subscriber.

Channel multiplexer is an object where one can register publisher and subscriber channels. When it is run, it continuously races the set of publishers and once it reads a value, it sends a copy to each subscriber.

When a publisher or subscriber channel is closed, it will be removed from the multiplexer's set.

For an unchanging set of publishers and subscribers and assuming that the multiplexer is the only reader of the publisher channels, every subscriber will receive the same set of messages, in the same order and it will be exactly all messages sent by the publishers. The only guarantee on the order of the values the subscribers see is that values from the same publisher will arrive in order.

Channel multiplexer can also be closed, in that case all subscribers will receive Failure(ChannelClosedException) but no attempt at closing either publishers or subscribers will be made.

Attributes

Companion
object
Supertypes
trait Closeable
trait AutoCloseable
class Object
trait Matchable
class Any
object ChannelMultiplexer

Attributes

Companion
trait
Supertypes
class Object
trait Matchable
class Any
Self type
class CompletionGroup extends Tracking

A group of cancellable objects that are completed together. Cancelling the group means cancelling all its uncompleted members.

A group of cancellable objects that are completed together. Cancelling the group means cancelling all its uncompleted members.

Attributes

Companion
object
Supertypes
trait Tracking
trait Cancellable
class Object
trait Matchable
class Any
Known subtypes
object Unlinked
object CompletionGroup

Attributes

Companion
class
Supertypes
class Object
trait Matchable
class Any
Self type
trait Future[+T] extends OriginalSource[Try[T]], Cancellable

Futures are Sources that has the following properties:

Futures are Sources that has the following properties:

  • They represent a single value: Once resolved, await-ing on a Future should always return the same value.
  • They can potentially be cancelled, via the cancel method.

There are two kinds of futures, active and passive.

  • '''Active''' futures are ones that are spawned with Future.apply and Task.start. They require the Async.Spawn context, and run on their own (as long as the Async.Spawn scope has not ended). Active futures represent concurrent computations within Gear's structured concurrency tree. Idiomatic Gears code should ''never'' return active futures. Should a function be async (i.e. takes an Async context parameter), they should return values or throw exceptions directly.
  • '''Passive''' futures are ones that are created by Future.Promise (through asFuture) and Future.withResolver. They represent yet-arrived values coming from ''outside'' of Gear's structured concurrency tree (for example, from network or the file system, or even from another concurrency system like Scala standard library futures). Idiomatic Gears libraries should return this kind of Future if deemed neccessary, but functions returning passive futures should ''not'' take an Async context.

Attributes

See also

Future.apply and Task.start for creating active futures.

Future.Promise and Future.withResolver for creating passive futures.

Future.awaitAll, Future.awaitFirst and Future.Collector for tools to work with multiple futures.

ScalaConverters.asGears and ScalaConverters.asScala for converting between Scala futures and Gears futures.

Companion
object
Supertypes
trait Cancellable
class OriginalSource[Try[T]]
trait Source[Try[T]]
class Object
trait Matchable
class Any
Show all
Known subtypes
trait Promise[T]
object Future

Attributes

Companion
trait
Supertypes
class Object
trait Matchable
class Any
Self type
Future.type
object JvmAsyncOperations extends AsyncOperations

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
trait Listener[-T]

A listener, representing an one-time value receiver of an Async.Source.

A listener, representing an one-time value receiver of an Async.Source.

Most of the time listeners should involve only calling a receiver function, and can be created by Listener.apply or Listener.acceptingListener.

However, should the listener want to attempt synchronization, it has to expose some locking-related interfaces. See Listener.lock.

Attributes

Companion
object
Supertypes
class Object
trait Matchable
class Any
Known subtypes
object Listener

Attributes

Companion
trait
Supertypes
class Object
trait Matchable
class Any
Self type
Listener.type
trait ReadableChannel[+T]

The part of a channel one can read values from. Blocking behavior depends on the implementation.

The part of a channel one can read values from. Blocking behavior depends on the implementation.

Attributes

Supertypes
class Object
trait Matchable
class Any
Known subtypes
trait Channel[T]
trait BufferedChannel[T]
trait UnboundedChannel[T]
trait SyncChannel[T]
trait Resource[+T]

A Resource wraps allocation to some asynchronously allocatable and releasable resource and grants access to it. It allows both structured access (similar to scala.util.Using) and unstructured allocation.

A Resource wraps allocation to some asynchronously allocatable and releasable resource and grants access to it. It allows both structured access (similar to scala.util.Using) and unstructured allocation.

Attributes

Companion
object
Supertypes
class Object
trait Matchable
class Any
Self type
object Resource

Attributes

Companion
trait
Supertypes
class Object
trait Matchable
class Any
Self type
Resource.type
case class Retry(retryOnSuccess: Boolean, maximumFailures: Option[Int], delay: Delay)

Utility class to perform asynchronous actions with retrying policies on exceptions.

Utility class to perform asynchronous actions with retrying policies on exceptions.

See Retry companion object for common policies as a starting point.

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object Retry

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
Retry.type
object ScalaConverters

Converters from Gears types to Scala API types and back.

Converters from Gears types to Scala API types and back.

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
trait Scheduler

A scheduler implementation, with the ability to execute a computation immediately or after a delay.

A scheduler implementation, with the ability to execute a computation immediately or after a delay.

Attributes

Supertypes
class Object
trait Matchable
class Any
Known subtypes
class Semaphore(initialValue: Int) extends Source[Guard]

A semaphore that manages a number of grants. One can wait to obtain a grant (with acquire) and return it to the semaphore (with release).

A semaphore that manages a number of grants. One can wait to obtain a grant (with acquire) and return it to the semaphore (with release).

Value parameters

initialValue

the initial counter of this semaphore

Attributes

Companion
object
Supertypes
trait Source[Guard]
class Object
trait Matchable
class Any
Self type
object Semaphore

Attributes

Companion
class
Supertypes
class Object
trait Matchable
class Any
Self type
Semaphore.type
trait SendableChannel[-T]

The part of a channel one can send values to. Blocking behavior depends on the implementation.

The part of a channel one can send values to. Blocking behavior depends on the implementation.

Attributes

Supertypes
class Object
trait Matchable
class Any
Known subtypes
trait Channel[T]
trait BufferedChannel[T]
trait UnboundedChannel[T]
trait SyncChannel[T]
trait SuspendSupport

Support for suspension capabilities through a delimited continuation interface.

Support for suspension capabilities through a delimited continuation interface.

Attributes

Supertypes
class Object
trait Matchable
class Any
Known subtypes
trait AsyncSupport
trait Suspension[-T, +R]

The delimited continuation suspension interface. Represents a suspended computation asking for a value of type T to continue (and eventually returning a value of type R).

The delimited continuation suspension interface. Represents a suspended computation asking for a value of type T to continue (and eventually returning a value of type R).

Attributes

Supertypes
class Object
trait Matchable
class Any
trait SyncChannel[T] extends Channel[T]

Synchronous channels, sometimes called rendez-vous channels, has the following semantics:

Synchronous channels, sometimes called rendez-vous channels, has the following semantics:

  • send to an unclosed channel blocks until a read listener commits to receiving the value (via successfully locking).

See SyncChannel$.apply for creation of synchronous channels.

Attributes

Companion
object
Supertypes
trait Channel[T]
trait Closeable
trait AutoCloseable
trait ReadableChannel[T]
trait SendableChannel[T]
class Object
trait Matchable
class Any
Show all
object SyncChannel

Attributes

Companion
trait
Supertypes
class Object
trait Matchable
class Any
Self type
class Task[+T](val body: (Async, AsyncOperations) ?=> T)

A task is a template that can be turned into a runnable future Composing tasks can be referentially transparent. Tasks can be also ran on a specified schedule.

A task is a template that can be turned into a runnable future Composing tasks can be referentially transparent. Tasks can be also ran on a specified schedule.

Attributes

Supertypes
class Object
trait Matchable
class Any
enum TaskSchedule

TaskSchedule describes the way in which a task should be repeated. Tasks can be set to run for example every 100 milliseconds or repeated as long as they fail. maxRepetitions describes the maximum amount of repetitions allowed, after that regardless of TaskSchedule chosen, the task is not repeated anymore and the last returned value is returned. maxRepetitions equal to zero means that repetitions can go on potentially forever.

TaskSchedule describes the way in which a task should be repeated. Tasks can be set to run for example every 100 milliseconds or repeated as long as they fail. maxRepetitions describes the maximum amount of repetitions allowed, after that regardless of TaskSchedule chosen, the task is not repeated anymore and the last returned value is returned. maxRepetitions equal to zero means that repetitions can go on potentially forever.

Attributes

Supertypes
trait Enum
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
class Timer(tickDuration: Duration) extends Cancellable

Timer exposes a steady Async.Source of ticks that happens every tickDuration milliseconds. Note that the timer does not start ticking until start is called (which is a blocking operation, until the timer is cancelled).

Timer exposes a steady Async.Source of ticks that happens every tickDuration milliseconds. Note that the timer does not start ticking until start is called (which is a blocking operation, until the timer is cancelled).

You might want to manually cancel the timer, so that it gets garbage collected (before the enclosing Async scope ends).

Attributes

Supertypes
trait Cancellable
class Object
trait Matchable
class Any
trait UnboundedChannel[T] extends BufferedChannel[T]

Unbounded channels are buffered channels that do not have an upper bound on the number of items in the channel. In other words, the buffer is treated as never being full and will expand as needed.

Unbounded channels are buffered channels that do not have an upper bound on the number of items in the channel. In other words, the buffer is treated as never being full and will expand as needed.

See UnboundedChannel$.apply for creation of unbounded channels.

Attributes

Companion
object
Supertypes
trait BufferedChannel[T]
trait Channel[T]
trait Closeable
trait AutoCloseable
trait ReadableChannel[T]
trait SendableChannel[T]
class Object
trait Matchable
class Any
Show all
object UnboundedChannel

Attributes

Companion
trait
Supertypes
class Object
trait Matchable
class Any
Self type
object VThreadScheduler extends Scheduler

Attributes

Supertypes
trait Scheduler
class Object
trait Matchable
class Any
Self type
opaque object VThreadSupport extends AsyncSupport

Attributes

Supertypes
trait AsyncSupport
class Object
trait Matchable
class Any
Self type

Types

type CancellationException = CancellationException

Value members

Concrete methods

def cancellationScope[T](cancellable: Cancellable)(fn: => T)(using a: Async): T

Link cancellable to the completion group of the current Async context during fn.

Link cancellable to the completion group of the current Async context during fn.

If the Async context is cancelled during the execution of fn, cancellable will also be immediately cancelled.

Attributes

def uninterruptible[T](body: Async ?=> T)(using ac: Async): T

Runs the body inside in an Async context that does not propagate cancellation until the end.

Runs the body inside in an Async context that does not propagate cancellation until the end.

In other words, body is never notified of the cancellation of the ac context; but uninterruptible would still throw a CancellationException ''after body finishes running'' if ac was cancelled.

Attributes

def withTimeout[T](timeout: FiniteDuration)(op: Async ?=> T)(using AsyncOperations, Async): T

Runs op with a timeout. When the timeout occurs, op is cancelled through the given Async context, and java.util.concurrent.TimeoutException is thrown.

Runs op with a timeout. When the timeout occurs, op is cancelled through the given Async context, and java.util.concurrent.TimeoutException is thrown.

Attributes

def withTimeoutOption[T](timeout: FiniteDuration)(op: Async ?=> T)(using AsyncOperations, Async): Option[T]

Runs op with a timeout. When the timeout occurs, op is cancelled through the given Async context, and None is returned.

Runs op with a timeout. When the timeout occurs, op is cancelled through the given Async context, and None is returned.

Attributes

Generated with