0
# Akka Actor Library
1

2
Akka Actor is a powerful toolkit for building highly concurrent, distributed, and resilient message-driven applications on the JVM. It provides an implementation of the Actor Model, where actors are the fundamental units of computation that communicate through asynchronous message passing.
3

4
## Package Information
5

6
### Maven Coordinates
7
```xml
8
<dependency>
9
    <groupId>com.typesafe.akka</groupId>
10
    <artifactId>akka-actor_2.12</artifactId>
11
    <version>2.8.8</version>
12
</dependency>
13
```
14

15
### SBT Dependency
16
```scala
17
libraryDependencies += "com.typesafe.akka" %% "akka-actor" % "2.8.8"
18
```
19

20
### Scala Version Compatibility
21
- Scala 2.12.x
22
- Scala 2.13.x (newer versions)
23

24
## Core Imports
25

26
```scala
27
import akka.actor._
28
import akka.pattern._
29
import akka.util.Timeout
30
import scala.concurrent.duration._
31
import scala.concurrent.Future
32
```{ .api }
33

34
## Basic Usage
35

36
### Creating an Actor System
37

38
```scala
39
import akka.actor.ActorSystem
40

41
val system = ActorSystem("MySystem")
42
```{ .api }
43

44
### Creating a Simple Actor
45

46
```scala
47
import akka.actor.{Actor, ActorRef, ActorSystem, Props}
48

49
class HelloActor extends Actor {
50
  def receive = {
51
    case "hello" => sender() ! "Hello back to you"
52
    case msg => println(s"Unknown message: $msg")
53
  }
54
}
55

56
val system = ActorSystem("HelloSystem")
57
val helloActor = system.actorOf(Props[HelloActor](), "hello-actor")
58

59
// Send a message (fire-and-forget)
60
helloActor ! "hello"
61
```{ .api }
62

63
### Actor with Constructor Parameters
64

65
```scala
66
class GreetingActor(greeting: String) extends Actor {
67
  def receive = {
68
    case name: String => sender() ! s"$greeting, $name!"
69
  }
70
}
71

72
val greetingActor = system.actorOf(Props(new GreetingActor("Hello")), "greeting-actor")
73
```{ .api }
74

75
### Request-Response with Ask Pattern
76

77
```scala
78
import akka.pattern.ask
79
import akka.util.Timeout
80
import scala.concurrent.duration._
81
import scala.concurrent.Future
82

83
implicit val timeout: Timeout = 5.seconds
84
implicit val ec = system.dispatcher
85

86
val future: Future[Any] = helloActor ? "hello"
87
future.foreach(println)
88
```{ .api }
89

90
## Architecture Overview
91

92
### Core Components
93

94
- **Actor**: The fundamental unit of computation that processes messages sequentially
95
- **ActorRef**: Immutable handle to an actor that enables message sending
96
- **ActorSystem**: Factory for actors and runtime for actor execution
97
- **Props**: Configuration object for creating actors (immutable and thread-safe)
98
- **ActorContext**: Context available to actors during message processing
99

100
### Actor Hierarchy
101

102
Actors are organized in a hierarchical structure where each actor has a parent (except the root guardian) and can create child actors. This hierarchy provides supervision and fault isolation.
103
104
```
105
ActorSystem
106
├── /user (user guardian)
107
│   ├── /user/my-actor
108
│   └── /user/another-actor
109
│       └── /user/another-actor/child-actor
110
└── /system (system guardian)
111
    ├── /system/deadLetters
112
    ├── /system/log
113
    └── ...
114
```
115

116
## Key Features
117

118
- **Location Transparency**: Actors can be local or remote without code changes
119
- **Fault Tolerance**: Supervisors handle actor failures automatically
120
- **Concurrency**: Actors process messages sequentially, avoiding shared mutable state
121
- **Scalability**: Millions of actors can exist in a single application
122
- **Message Routing**: Flexible message routing and load balancing
123
- **Finite State Machines**: Built-in FSM support for stateful actors
124

125
## Documentation Sections
126

127
### [Core Actors](core-actors.md)
128
Comprehensive coverage of the core actor classes and interfaces including `Actor`, `AbstractActor`, `ActorRef`, `Props`, and `ActorSystem`. Learn how to create, configure, and manage actors.
129

130
### [Actor Lifecycle](actor-lifecycle.md)
131
Actor lifecycle management, supervision strategies, fault tolerance mechanisms, and the actor restart process. Understanding how actors are born, supervised, and terminated.
132

133
### [Routing](routing.md) 
134
Router configurations, routing strategies, and load balancing. Learn about round-robin, random, smallest mailbox, and other routing algorithms for distributing messages across multiple actors.
135

136
### [Patterns](patterns.md)
137
Common actor patterns including the ask pattern for request-response, pipeTo for forwarding Future results, graceful shutdown procedures, and other essential patterns.
138

139
### [FSM (Finite State Machines)](fsm.md)
140
Built-in finite state machine support for creating stateful actors that transition between different states based on events and conditions.
141

142
### [Messaging](messaging.md)
143
Message types, actor selection, addressing, dead letters, and communication patterns. Understanding how actors find and communicate with each other.
144

145
### [Scheduling](scheduling.md)
146
Scheduling operations, timers, timeout handling, and periodic tasks. Learn how to schedule work in the actor system.
147

148
### [I/O & Networking](io-networking.md)
149
Network I/O operations, TCP and UDP support, and integration with Akka I/O for building networked applications.
150

151
## Quick Reference
152

153
### Essential Actor Methods
154

155
```scala
156
// In Actor trait
157
def receive: Receive  // Abstract method for message handling
158
def sender(): ActorRef  // Sender of current message
159
def context: ActorContext  // Actor context
160
def self: ActorRef  // Reference to this actor
161
```{ .api }
162

163
### Essential ActorRef Methods
164

165
```scala
166
// Sending messages
167
actorRef ! message  // Fire-and-forget
168
actorRef.tell(message, sender)  // With explicit sender
169
actorRef.forward(message)  // Forward with original sender
170
```{ .api }
171

172
### Essential ActorSystem Methods
173

174
```scala
175
// Creating actors
176
system.actorOf(props, "name")  // Create top-level actor
177
system.stop(actorRef)  // Stop an actor
178
system.terminate()  // Shutdown actor system
179
```{ .api }
180

181
### Essential ActorContext Methods
182

183
```scala
184
// In actor
185
context.actorOf(props, "child")  // Create child actor
186
context.stop(actorRef)  // Stop child actor
187
context.watch(actorRef)  // Watch for termination
188
context.become(newBehavior)  // Change behavior
189
```{ .api }
190

191
This comprehensive documentation covers all aspects of the Akka Actor library, from basic usage to advanced patterns and configurations. Each section provides detailed API documentation with practical examples.