https://github.com/jkrumow/actorkit
A lightweight actor framework in Objective-C.
https://github.com/jkrumow/actorkit
actors actors-supervision supervision
Last synced: 6 months ago
JSON representation
A lightweight actor framework in Objective-C.
- Host: GitHub
- URL: https://github.com/jkrumow/actorkit
- Owner: jkrumow
- License: mit
- Created: 2015-08-03T20:51:20.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2023-05-01T10:45:37.000Z (over 2 years ago)
- Last Synced: 2025-03-25T15:08:02.888Z (7 months ago)
- Topics: actors, actors-supervision, supervision
- Language: Objective-C
- Size: 687 KB
- Stars: 13
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# ActorKit
[](http://cocoadocs.org/docsets/ActorKit)
[](http://cocoadocs.org/docsets/ActorKit)
[](http://cocoadocs.org/docsets/ActorKit)
[](https://travis-ci.org/jkrumow/ActorKit)
A lightweight actor framework in Objective-C.
## Features
* Actors
* Actor Pools
* Synchronous and asynchronous invocations
* Promises
* Notification subscription and publication
* Supervision
* Linking
## Requirements
* iOS 8.0
* watchOS 2.0
* tvOS 9.0
* OS X 10.10
## Installation
ActorKit is available through [CocoaPods](http://cocoapods.org). To install
it, simply add the following line to your Podfile:
```ruby
pod 'ActorKit'
```
## Usage
Any object derived from `NSObject` can be turned into an actor by importing ``.
```objc
`#import `
Worker *worker = [[Worker alloc] initWithName:@"Bee"];
NSMutableArray *array = [NSMutableArray new];
```
As soon as you start sending messages to them as described below they will behave like actors automatically. There is nothing else you have to do.
### Sending Messages to Actors
To send a synchronous message to the actor precede the call with `sync`:
```objc
BOOL success = [worker.sync doSomething];
```
Send an asynchronous message to the actor use `async`:
```objc
[array.async removeAllObjects];
```
### Publishing notifications to other actors
Publish a notification with a payload:
```objc
[self publish:@"notification" payload:@5];
```
### Subscribing to notifications from other actors
To subscribe to a notification set the notification name and a selector which takes the notification's payload as an argument:
```objc
[worker subscribe:@"notification" selector:@selector(handler:)];
- (void)handler:(NSNumber *)number
{
// ...
}
```
To unsubscribe from a notification:
```objc
[worker unsubscribe:@"notification"];
```
Before destroying an actor you should unsubscribe from all notifications.
### Actor Pools
The class `TBActorPool` is basically a proxy actor which mananges multiple actors of the same type. A message which is send to the pool will be forwarded to an actor inside the pool which has the lowest workload at the time the message is processed.
You can create an actor pool by invoking the method below on the class of your choice. An actor instance will be created and passed into the configuration block for further initialization:
```objc
TBActorPool *pool = [Worker poolWithSize:10 configuration:^(NSObject *actor) {
Worker *worker = (Worker *)actor;
worker.name = @"worker";
worker.Id = @(123);
}];
```
You can send messages to the pool:
```objc
[pool.sync setName:@"worker"];
[pool.async doSomething];
```
Same goes for subscriptions:
```objc
[pool subscribe:@"notificationToWorkers" selector:@selector(handler:)];
[pool unsubscribe:@"notificationToWorkers"];
```
The handler will be executed by an available actor in the pool.
#### Broadcasts
To send an asynchronous message to all actors inside the pool:
```objc
[pool.broadcast ping];
```
### Promises
Promise support using [PromiseKit](http://promisekit.org) is available via the subspec `Promises`:
```ruby
target 'MyApp', :exclusive => true do
pod 'ActorKit/Promises'
end
```
```objc
#import
```
Send a asynchronous message and receive a promise back:
```objc
((AnyPromise *)[worker.promise returnSomethingBlocking])
.then(^(id result) {
// ...
});
```
### Supervision and Linking of Actors
Supervision and Linking is available via the subspec `Supervision`:
```ruby
target 'MyApp', :exclusive => true do
pod 'ActorKit/Supervision'
end
```
```objc
#import
```
#### Supervised Actors
You can create supervised actors by passing an id and a creation block to a supervision pool:
```objc
TBActorSupervisionPool *actors = [TBActorSupervisionPool new];
[actors superviseWithId:@"master" creationBlock:^NSObject * {
Worker *worker = Worker.new;
worker.name = @"master";
worker.Id = @(123);
return worker;
}];
```
The creation block will be called whenever the actor needs to be (re)created.
#### Accessing Actors Inside the Supervision Pool
Access the supervised actor by its id on the supervision pool:
```objc
[actors[@"master"].sync doSomething];
```
#### Unsupervising Actors
To remove an actor from a supervision pool:
```objc
[actors unsuperviseActorWithId:@"master"];
```
#### Linking Actors
Links establish parent-child relationships between actors. Linked actors will be supervised depending on each other. If the parent actor crashes the child actor will be re-created as well. Whenever an actor is removed from the supervision pool its linked actors are removed as well.
```objc
[actors linkActor:@"child" toParentActor:@"master"];
```
To remove a link:
```objc
[actors unlinkActor:@"child" fromParentActor:@"master"];
```
#### Recovering from Crashes
Whenever a supervised actor crashes it is re-created and will resume processing pending messages from its mailbox.
**Special behavior for pools:**
- when the pool actor itself crashes the whole pool is recreated completely and the content of all mailboxes will be processed by the new pool instance
- when an actor inside the pool crashes only that instance is recreated and its mailbox content will be processed by its successor
You can also communicate a crash manually by calling `crashWithError:`:
```objc
@implementation Worker
- (void)doSomething
{
NSError *error = nil;
[self _doSomethingInternal:&error];
if (error) {
[self crashWithError:error];
}
}
@end
```
**Attention:** Cocoa is not a framework which employs exceptions as a legitimate means to communicate errors. There are a lot of layers which prevent exceptions to bubble up the stack until they can be handled by the supervisor (GCD etc.). So be prepared for exceptions which still can crash the application.
**Warning:** Scheduling your own operations on the actor queue directly is strongly discouraged since the supervision can not guarantee that this operations can be executed properly by the new actor instance.
## Architecture
This framework seeks for a very simple implementation of actors. It basically consists of a category which lazily adds an `NSOperationQueue` to the `NSObject` which should work as an actor. Messages sent to the actor are forwarded by an `NSProxy` using `NSInvocation` and `NSOperation` objects. These classes represent mailboxes, threads and messages etc.
## Example Project
To run the example project, clone the repo, and run `pod install` from the `./ActorKit` directory first.
## Useful Theory on Actors
- https://en.wikipedia.org/wiki/Actor_model
## Author
Julian Krumow, julian.krumow@bogusmachine.com
## License
ActorKit is available under the MIT license. See the LICENSE file for more info.