Enhancing Actor Docs and Adding Actor Concepts

Adding actor concepts and enhancing the existing docs

concepts/actor/actor_overview.md

@@ -0,0 +1,69 @@
+# Introduction to Actors
+Actors is an application pattern based on the Virtual Actor pattern. 
+Dapr programming model enables writing the actor pattern. The Actors API provides a single-threaded programming model built on the scalability and reliability guarantees.
+
+## What are Actors?
+
+An actor is an isolated, independent unit of compute and state with single-threaded execution. 
+
+The [actor pattern](https://en.wikipedia.org/wiki/Actor_model) is a computational model for concurrent or distributed systems in which a large number of these actors can execute simultaneously and independently of each other. Actors can communicate with each other and they can create more actors.
+
+### When to use Actors
+
+Dapr Actors is an implementation of the actor design pattern. As with any software design pattern, the decision whether to use a specific pattern is made based on whether or not a software design problem fits the pattern.
+
+Although the actor design pattern can be a good fit to a number of distributed systems problems and scenarios, careful consideration of the constraints of the pattern and the framework implementing it must be made. As general guidance, consider the actor pattern to model your problem or scenario if:
+
+* Your problem space involves a large number (thousands or more) of small, independent, and isolated units of state and logic.
+* You want to work with single-threaded objects that do not require significant interaction from external components, including querying state across a set of actors.
+* Your actor instances won't block callers with unpredictable delays by issuing I/O operations.
+
+# Actors in Dapr
+
+Every actor is defined as an instance of an actor type, identical to the way a .NET object is an instance of a .NET type. For example, there may be an actor type that implements the functionality of a calculator and there could be many actors of that type that are distributed on various nodes across a cluster. Each such actor is uniquely identified by an actor ID.
+
+# Actor Lifetime
+
+Dapr actors are virtual, meaning that their lifetime is not tied to their in-memory representation. As a result, they do not need to be explicitly created or destroyed. The Dapr Actors runtime automatically activates an actor the first time it receives a request for that actor ID. If an actor is not used for a period of time, the Dapr Actors runtime garbage-collects the in-memory object. It will also maintain knowledge of the actor's existence should it need to be reactivated later. For more details, see Actor lifecycle and garbage collection.
+
+This virtual actor lifetime abstraction carries some caveats as a result of the virtual actor model, and in fact the Reliable Actors implementation deviates at times from this model.
+
+An actor is automatically activated (causing an actor object to be constructed) the first time a message is sent to its actor ID. After some period of time, the actor object is garbage collected. In the future, using the actor ID again, causes a new actor object to be constructed. An actor's state outlives the object's lifetime when storing the state in Dapr.
+
+# Distribution and failover
+To provide scalability and reliability, actors instances are distributed throughout the cluster and automatically migrates them from failed nodes to healthy ones as required.
+
+Actors are distributed across the pods of the Actor Service, and those pods are distributed across the nodes in a cluster. Each service partition contains a set of actors
+
+The Dapr Actor runtime manages distribution scheme and key range settings for you. This simplifies some choices but also carries some consideration:
+
+* Dapr Actors is using the range partitioning scheme.
+* By default, actors are randomly placed into pods resulting in uniform distribution.
+* Because actors are randomly placed, it should be expected that actor operations will always require network communication, including serialization and deserialization of method call data, incurring latency and overhead.
+
+# Actor communication
+
+You can interact with Dapr to invoke the actor method by calling Http/gRPC endpoint
+
+```
+POST/GET/PUT/DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/method/<method>
+```
+
+If you want to pass the method parameters, then you can pass in request body.
+
+Refer [dapr spec](/dapr/spec/blob/master/actors.md) for more details.
+
+Since Method invocations and their responses ultimately result in network requests across the cluster, so the arguments and the result types of the tasks that they return must be serializable.
+
+### Concurrency
+
+The Dapr Actors runtime provides a simple turn-based access model for accessing actor methods. This means that no more than one thread can be active inside an actor object's code at any time. Turn-based access greatly simplifies concurrent systems as there is no need for synchronization mechanisms for data access. It also means systems must be designed with special considerations for the single-threaded access nature of each actor instance.
+
+A single actor instance cannot process more than one request at a time. An actor instance can cause a throughput bottleneck if it is expected to handle concurrent requests.
+
+Actors can deadlock on each other if there is a circular request between two actors while an external request is made to one of the actors simultaneously. The Dapr actor runtime will automatically time out on actor calls and throw an exception to the caller to interrupt possible deadlock situations.
+
+### Turn-based access
+A turn consists of the complete execution of an actor method in response to a request from other actors or clients, or the complete execution of a timer/reminder callback. Even though these methods and callbacks are asynchronous, the Dapr Actors runtime does not interleave them. A turn must be fully finished before a new turn is allowed. In other words, an actor method or timer/reminder callback that is currently executing must be fully finished before a new call to a method or callback is allowed. A method or callback is considered to have finished if the execution has returned from the method or callback and the task returned by the method or callback has finished. It is worth emphasizing that turn-based concurrency is respected even across different methods, timers, and callbacks.
+
+The Dapr Actors runtime enforces turn-based concurrency by acquiring a per-actor lock at the beginning of a turn and releasing the lock at the end of the turn. Thus, turn-based concurrency is enforced on a per-actor basis and not across actors. Actor methods and timer/reminder callbacks can execute simultaneously on behalf of different actors.

concepts/actor/actors_features.md

@@ -0,0 +1,118 @@
+# Dapr Actors Runtime 
+
+Dapr Actors runtime provides capability to use Actor pattern features.
+
+## Actor State Management
+ Actors are single-threaded objects that can encapsulate both logic and state. Because Dapr provides the state management, so Actors can maintain state reliably by using the same persistence and replication mechanisms. This way, actors don't lose their state after failures, upon reactivation after garbage collection, or when they are moved around between pods in a cluster due to resource balancing or upgrades.
+
+ You can interact with Dapr Actors runtime through Http/gRPC endpoints for state management.
+
+ ### Save the Actor State
+
+You can save the Actor state of a given key of actorId of type actorType by calling
+
+```
+POST/PUT http://localhost:3500/v1.0/actors/<actorType>/<actorId>/state/<key>
+```
+
+Value of the key is passed as request body.
+
+```
+{
+  "key": "value"
+}
+```
+
+If you want to save multiple items in a single transaction, you can call 
+
+```
+POST/PUT http://localhost:3500/v1.0/actors/<actorType>/<actorId>/state
+```
+
+### Retrieve the Actor State
+
+Once you have saved the actor state, you can retrived the saved state by calling 
+
+```
+GET http://localhost:3500/v1.0/actors/<actorType>/<actorId>/state/<key>
+```
+
+### Remove the Actor State
+
+You can remove state permanently from the saved Actor state by calling
+
+```
+DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/state/<key>
+```
+
+Refer [dapr spec](/dapr/spec/blob/master/actors.md) for more details.
+
+## Actor Timers and Reminders
+Actors can schedule periodic work on themselves by registering either timers or reminders.
+
+### Actor timers
+
+You can register a callback on actor to be executed based on 
+timer.
+
+Dapr Actor runtime ensures that the callback methods respect the turn-based concurrency guarantees.This means that no other actor methods or timer/reminder callbacks will be in progress until this callback completes execution.
+
+The next period of the timer starts after the callback completes execution. This implies that the timer is stopped while the callback is executing and is started when the callback finishes.
+
+The Dapr Actors runtime saves changes made to the actor's state when the callback finishes. If an error occurs in saving the state, that actor object will be deactivated and a new instance will be activated.
+
+All timers are stopped when the actor is deactivated as part of garbage collection. No timer callbacks are invoked after that. Also, the Dapr Actors runtime does not retain any information about the timers that were running before deactivation. It is up to the actor to register any timers that it needs when it is reactivated in the future.
+
+You can create a timer for an actor by calling the Http/gRPC request to Darp.
+
+```
+POST,PUT http://localhost:3500/v1.0/actors/<actorType>/<actorId>/timers/<name>
+```
+
+You can provide the timer due time and callback in the request body.
+
+You can remove the actor timer  by calling
+
+```
+DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/timers/<name>
+```
+
+Refer [dapr spec](/dapr/spec/blob/master/actors.md) for more details.
+
+### Actor reminders
+
+Reminders are a mechanism to trigger persistent callbacks on an actor at specified times. Their functionality is similar to timers. But unlike timers, reminders are triggered under all circumstances until the actor explicitly unregisters them or the actor is explicitly deleted. Specifically, reminders are triggered across actor deactivations and failovers because the Dapr Actors runtime persists information about the actor's reminders using Dapr actor state provider. 
+
+You can create a persistent reminder for an actor by calling the Http/gRPC request to Darp.
+
+```
+POST,PUT POST,PUT http://localhost:3500/v1.0/actors/<actorType>/<actorId>/reminders/<name>
+```
+
+You can provide the reminder due time and period in the request body.
+
+#### Retrieve Actor Reminder
+
+You can retrieve the actor reminder by calling
+
+```
+GET http://localhost:3500/v1.0/actors/<actorType>/<actorId>/reminders/<name>
+```
+
+#### Remove the Actor Reminder
+
+You can remove the actor reminder by calling
+
+```
+DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/reminders/<name>
+```
+
+Refer [dapr spec](/dapr/spec/blob/master/actors.md) for more details.
+
+
+
+
+
+
+
+

concepts/actor/actors_integration.md

@@ -31,7 +31,7 @@ The following diagram illustrates two possible execution paths. ![Actors server]
 At a high level, the Actor API shall contain the following methods:
 
 * Dispatch to Actor when possible
-* Call method on an Actor now
+* Call method on an Actor
 * Load/save state
 * Create/remove
 * Locate & send message to an Actor