DOCSEARCHbyAlgolia
Submit Docs

Apache Pekko Documentation

repository·main·Indexed 23 days ago

https://github.com/apache/pekko

An open-source framework for building concurrent, distributed, resilient, and elastic applications using the Actor Model. A fork of Akka 2.6.x, it provides high-level abstractions and libraries for persistence, streams, and HTTP. Documentation includes guides on building from source with JDK 17 and sbt, running JMH microbenchmarks, and using testing tools like BehaviorTestKit, LoggingTestKit, and ActorTestKitBase.

Tokens
201.6K
Snippets
104
Records
1.2K
Agent score
82%

What's inside Apache Pekko

  1. What is Apache Pekko?

    main
    Apache Pekko is an open-source framework designed for building concurrent, distributed, resilient, and elastic applications. It utilizes the Actor Model to provide high-level abstractions for concurrency. Beyond the core actor system, Pekko provides specialized libraries for persistence, streams, HTTP, and other distributed computing needs. It is a fork of Akka 2.6.x and includes some features from Akka 2.7.0.

  2. What is Apache Pekko and how does it work?

    main

    Apache Pekko is a set of open-source libraries designed for building scalable, resilient, and distributed systems. It uses the actor model to provide a high-level abstraction for concurrent, parallel, and distributed computing.

    Core Capabilities

    • Multi-threaded behavior: Provides concurrency without requiring low-level constructs like atomics or locks, managing memory visibility automatically.
    • Transparent remote communication: Enables communication between systems and components without requiring manual networking code.
    • Clustered, high-availability architecture: Supports elastic scaling (in or out) on demand to create reactive systems.

    By using the actor model, Pekko provides a consistent programming model across its entire suite of libraries, ensuring that different modules integrate tightly and efficiently.

  4. Introduction to Pekko Distributed Data

    main

    Pekko Distributed Data allows you to share data between nodes in a Pekko Cluster using a key-value store API.

    Core Concepts:

    • Keys: Unique identifiers that include type information for the associated data values.
    • Values (CRDTs): Data is stored as Conflict Free Replicated Data Types (CRDTs). These types use a monotonic merge function to automatically resolve concurrent updates from different nodes without coordination.
    • Replication: Data is disseminated across all nodes (or nodes with specific roles) via direct replication and gossip-based protocols.
    • Consistency Model: The system is eventually consistent, prioritizing high availability and low latency (partition tolerance). While updates converge automatically, reads may occasionally return out-of-date values.
    • Data Types: Pekko provides built-in CRDTs for counters, sets, maps, and registers, but allows for custom implementations.

  6. Key features and changes in Artery Remoting

    main

    Artery is a high-performance reimplementation of the Pekko remoting module. It is designed for high-throughput, low-latency communication and is mostly source-compatible with the old implementation.

    Main Features

    • Transport Options: Based on Pekko Streams TCP/TLS or Aeron (UDP) instead of Netty TCP.
    • Stability: Isolates internal control messages from user messages using a dedicated subchannel to prevent false failure detection during heavy traffic.
    • Performance: Mostly allocation-free operation and support for direct ByteBuffer serialization.
    • Large Messages: Supports a separate subchannel for large messages to prevent interference with small messages.
    • Efficiency: Compresses actor paths on the wire.
    • Observability: Built-in Java Flight Recorder (JFR) support.
    • Protocol Stability: Provides protocol stability across major Pekko versions to support rolling updates.

    Breaking Changes

    • ActorRef String Representation: The protocol field in the string representation of an ActorRef is always pekko (previously pekko.tcp or pekko.ssl.tcp).
    • Configuration: Configuration properties have changed from the old implementation.

  7. Use Pekko Artery instead of Classic Remoting

    main

    ⚠️ Warning: Classic Remoting is deprecated.

    Classic Remoting is the legacy mechanism for Actor communication across nodes. For all new Pekko applications, you should use Artery instead. While Remoting is the underlying module for Pekko Cluster, it is recommended to use high-level utilities like Pekko Cluster or technology-agnostic protocols like HTTP or gRPC for most use cases.

  8. Explore Higher-level Pekko Cluster Tools

    main

    Pekko Cluster provides several high-level abstractions for distributed computing:

    • Cluster Singleton: Ensures a single instance of an actor runs in the cluster.
    • Cluster Sharding: Automatically distributes actors across the cluster based on entity IDs.
    • Distributed Data (DData): Provides eventually consistent, replicated data structures.
    • Distributed Publish Subscribe: Enables messaging between nodes via a pub-sub pattern.
    • Group Routers: Allows routing messages to a group of actors across the cluster.
    • Cluster Multi-DC: Supports running multiple data centers within a single cluster.
    • Reliable Delivery: Provides mechanisms for ensuring message delivery across nodes.

  9. Use Classic Clustering in Apache Pekko

    main

    Apache Pekko provides a 'Classic Clustering' API for managing distributed actor systems. This API is used for managing actor lifecycles, routing, and data distribution across multiple nodes in a cluster.

    Note: If you are starting a new project, consider using the new Typed API for clustering instead of the Classic API. For information on the new API, refer to the Cluster documentation in the typed module.

  10. What is a Router Actor (Pool vs Group)

    main

    A router actor is a self-contained actor that manages routees based on configuration. There are two main types:

    1. Pool: The router creates routees as child actors. It manages their lifecycle and removes them if they terminate. If a child in a pool terminates, the pool does not automatically spawn a new one unless it is a dynamic router (e.g., using a resizer).
    2. Group: Routees are created externally. The router sends messages to the specified paths using ActorSelection. It does not watch for routee termination.

    To allow an actor to accept routing settings from configuration, you must wrap its props with FromConfig.

  11. What is Stashing in Pekko Actor Typed?

    main

    Stashing allows an actor to temporarily buffer all or some messages that cannot or should not be handled using the actor's current behavior.

    Common use cases include:

    • Initialization: Buffering messages while the actor loads initial state or initializes resources.
    • Sequential Processing: Buffering messages while waiting for a specific task to complete to ensure processing remains sequential and avoids multiple pending writes.

    Important Constraints:

    • Memory Usage: Stashed messages are kept in memory. Stashing too many messages can lead to java.lang.OutOfMemoryError.
    • Bounded Buffer: The StashBuffer is bounded. You must specify a capacity when creating it. If you exceed this capacity, a typed.*.StashOverflowException is thrown.
    • Unstashing Behavior: When using unstashAll, messages are processed sequentially in the order they were added. The actor remains unresponsive to new messages until unstashAll is completed, which can lead to actor starvation if the buffer is too large.

  12. What is a Sharded Daemon Process and when to use it

    main

    A Sharded Daemon Process runs N actors, each assigned a numeric ID starting from 0. These actors are kept alive and balanced across the cluster. When a rebalance occurs, the actor is stopped and restarted (managed via a Cluster Singleton keep-alive mechanism).

    Use Cases:

    • Splitting data processing workloads across a fixed set of workers.
    • Creating projections in CQRS applications by tagging events with one of N tags to distribute the workload.

    Note: If you only need a single actor to be kept alive, use Cluster Singleton instead.