Skip to main content
Version: 2.x

Introduction

ZIO contains a few data types that can help you solve complex problems in asynchronous and concurrent programming. ZIO data types categorize into these sections:

  1. Core Data Types
  2. Contextual Data Types
  3. State Management
  4. Concurrency
  5. Resource Management
  6. Streaming
  7. Metrics
  8. Testing
  9. Miscellaneous

Core Data Types

  • ZIOZIO is a value that models an effectful program, which might fail or succeed.
    • UIOUIO[A] is a type alias for ZIO[Any, Nothing, A].
    • URIOURIO[R, A] is a type alias for ZIO[R, Nothing, A].
    • TaskTask[A] is a type alias for ZIO[Any, Throwable, A].
    • RIORIO[R, A] is a type alias for ZIO[R, Throwable, A].
    • IOIO[E, A] is a type alias for ZIO[Any, E, A].
  • ZIOAppZIOApp and the ZIOAppDefault are entry points for ZIO applications.
  • RuntimeRuntime[R] is capable of executing tasks within an environment R.
  • ExitExit[E, A] describes the result of executing an IO value.
  • CauseCause[E] is a description of a full story of a fiber failure.

Contextual Data Types

  • ZEnvironmentZEnvironment[R] is a built-in type-level map for the ZIO data type which is responsible for maintaining the environment of a ZIO effect.
  • ZLayerZLayer[-RIn, +E, +ROut] is a recipe to build an environment of type ROut, starting from a value RIn, and possibly producing an error E during creation.
    • RLayerRLayer[-RIn, +ROut] is a type alias for ZLayer[RIn, Throwable, ROut], which represents a layer that requires RIn as its input, it may fail with Throwable value, or returns ROut as its output.
    • ULayerULayer[+ROut] is a type alias for ZLayer[Any, Nothing, ROut], which represents a layer that doesn't require any services as its input, it can't fail, and returns ROut as its output.
    • LayerLayer[+E, +ROut] is a type alias for ZLayer[Any, E, ROut], which represents a layer that doesn't require any services, it may fail with an error type of E, and returns ROut as its output.
    • URLayerURLayer[-RIn, +ROut] is a type alias for ZLayer[RIn, Nothing, ROut], which represents a layer that requires RIn as its input, it can't fail, and returns ROut as its output.
    • TaskLayerTaskLayer[+ROut] is a type alias for ZLayer[Any, Throwable, ROut], which represents a layer that doesn't require any services as its input, it may fail with Throwable value, and returns ROut as its output.

State Management

  • ZState— It models a state that can be read from and written to during the execution of an effect.
  • RefRef[A] models a mutable reference to a value of type A.
  • FiberRefFiberRef[A] models a mutable reference to a value of type A. As opposed to Ref[A], a value is bound to an executing Fiber only. You can think of it as Java's ThreadLocal on steroids.

Concurrency

Fiber Primitives

  • Fiber — A fiber value models an IO value that has started running, and is the moral equivalent of a green thread.
  • Fiber.StatusFiber.Status describe the current status of a Fiber.
  • FiberIdFiberId describe the unique identity of a Fiber.

Concurrency Primitives

  • Hub — A Hub is an asynchronous message hub that allows publishers to efficiently broadcast values to many subscribers.
  • Promise — A Promise is a model of a variable that may be set a single time, and awaited on by many fibers.
  • Semaphore — A Semaphore is an asynchronous (non-blocking) semaphore that plays well with ZIO's interruption.
  • RefRef[A] models a mutable reference to a value of type A. The two basic operations are set, which fills the Ref with a new value, and get, which retrieves its current content. All operations on a Ref are atomic and thread-safe, providing a reliable foundation for synchronizing concurrent programs.
  • Ref.SynchronizedRef.Synchronized[A] models a mutable reference to a value of type A in which we can store immutable data, and update it atomically and effectfully.
  • Queue — A Queue is an asynchronous queue that never blocks, which is safe for multiple concurrent producers and consumers.

Synchronization Aids

  • ReentrantLock— The ReentrantLock is a synchronization tool that is useful for synchronizing blocks of code.
  • CountdownLatch — A synchronization aid that allows one or more fibers to wait until a set of operations being performed in other fibers completes.
  • CyclicBarrier — A synchronization aid that allows a set of fibers to all wait for each other to reach a common barrier point.
  • ConcurrentMap — A Map wrapper over java.util.concurrent.ConcurrentHashMap
  • ConcurrentSet — A Set implementation over java.util.concurrent.ConcurrentHashMap

STM

  • STM — An STM represents an effect that can be performed transactionally resulting in a failure or success.
  • TArray — A TArray is an array of mutable references that can participate in transactions.
  • TSet — A TSet is a mutable set that can participate in transactions.
  • TMap — A TMap is a mutable map that can participate in transactions.
  • TRef — A TRef is a mutable reference to an immutable value that can participate in transactions.
  • TPriorityQueue — A TPriorityQueue is a mutable priority queue that can participate in transactions.
  • TPromise — A TPromise is a mutable reference that can be set exactly once and can participate in transactions.
  • TQueue — A TQueue is a mutable queue that can participate in transactions.
  • TReentrantLock — A TReentrantLock is a reentrant read / write lock that can be composed.
  • TSemaphore — A TSemaphore is a semaphore that can participate in transactions.

Resource Management

  • Scope — A scope in which resources can safely be used.
  • ZPool — An asynchronous and concurrent generalized pool of reusable resources.

Streaming

  • ZStreamZStream is a lazy, concurrent, asynchronous source of values.
    • StreamStream[E, A] is a type alias for ZStream[Any, E, A], which represents a ZIO stream that does not require any services, and may fail with an E, or produce elements with an A.
  • ZSinkZSink is a consumer of values from a ZStream, which may produce a value when it has consumed enough.
    • SinkSink[InErr, A, OutErr, L, B] is a type alias for ZSink[Any, InErr, A, OutErr, L, B].
  • ZPipelineZPipeline is a polymorphic stream transformer.
  • SubscriptionRefSubscriptionRef[A] contains a current value of type A and a stream that can be consumed to observe all changes to that value.

Metrics

IO supports 5 types of Metrics:

  • Counter — The Counter is used for any value that increases over time like request counts.
  • Gauge — The gauge is a single numerical value that can arbitrary goes up or down over time like memory usage.
  • Histogram — The Histogram is used to track the distribution of a set of observed values across a set of buckets like request latencies.
  • Summary — The Summary represents a sliding window of a time series along with metrics for certain percentiles of the time series, referred to as quantiles like request latencies.
  • Frequency — The Frequency is a metric that counts the number of occurrences of distinct string values.

Testing

  • Spec— A Spec[R, E] is the backbone of ZIO Test. All specs require an environment of type R and may potentially fail with an error of type E.
  • Assertion— An Assertion[A] is a test assertion that can be used to assert the predicate of type A => Boolean.
  • TestAspect— A TestAspect is an aspect that can be weaved into specs. We can think of an aspect as a polymorphic function, capable of transforming one test into another.
  • Gen— A Gen[R, A] represents a generator of values of type A, which requires an environment R.
  • Test Service— ZIO Test has the following out-of-the-box test services:
    • TestConsole— It allows testing of applications that interact with the console.
    • TestClock— We can deterministically and efficiently test effects involving the passage of time without actually having to wait for the full amount of time to pass.
    • TestRandom— This service allows us having fully deterministic testing of code that deals with Randomness.
    • TestSystem— It supports deterministic testing of effects involving system properties.
    • Live— It provides access to the live environment from within the test environment for effects.
    • TestConfig— It provides access to default configuration settings used by ZIO Test.
    • Sized— It enables Sized Generators to access the size from the ZIO Test environment.

Miscellaneous

  • ChunkChunk is a fast, pure alternative to Arrays.
  • SupervisorSupervisor[A] is allowed to supervise the launching and termination of fibers, producing some visible value of type A from the supervision.

To learn more about these data types, please explore the pages above, or check out the Scaladoc documentation.