Docs: Removed pending
This commit is contained in:
Patrik Nordwall
parent
5b08cf5907
commit
b455dffc04
9 changed files with 0 additions and 464 deletions
|
|
@ -1,55 +0,0 @@
|
|||
Using Akka in a Buildr project
|
||||
==============================
|
||||
|
||||
This is an example on how to use Akka in a project based on Buildr
|
||||
|
||||
.. code-block:: ruby
|
||||
|
||||
require 'buildr/scala'
|
||||
|
||||
VERSION_NUMBER = "0.6"
|
||||
GROUP = "se.scalablesolutions.akka"
|
||||
|
||||
repositories.remote << "http://www.ibiblio.org/maven2/"
|
||||
repositories.remote << "http://www.lag.net/repo"
|
||||
repositories.remote << "http://multiverse.googlecode.com/svn/maven-repository/releases"
|
||||
|
||||
AKKA = group('akka-core', 'akka-comet', 'akka-util','akka-kernel', 'akka-rest', 'akka-util-java',
|
||||
'akka-security','akka-persistence-common', 'akka-persistence-redis',
|
||||
'akka-amqp',
|
||||
:under=> 'se.scalablesolutions.akka',
|
||||
:version => '0.6')
|
||||
ASPECTJ = "org.codehaus.aspectwerkz:aspectwerkz-nodeps-jdk5:jar:2.1"
|
||||
SBINARY = "sbinary:sbinary:jar:0.3"
|
||||
COMMONS_IO = "commons-io:commons-io:jar:1.4"
|
||||
CONFIGGY = "net.lag:configgy:jar:1.4.7"
|
||||
JACKSON = group('jackson-core-asl', 'jackson-mapper-asl',
|
||||
:under=> 'org.codehaus.jackson',
|
||||
:version => '1.2.1')
|
||||
MULTIVERSE = "org.multiverse:multiverse-alpha:jar:jar-with-dependencies:0.3"
|
||||
NETTY = "org.jboss.netty:netty:jar:3.2.0.ALPHA2"
|
||||
PROTOBUF = "com.google.protobuf:protobuf-java:jar:2.2.0"
|
||||
REDIS = "com.redis:redisclient:jar:1.0.1"
|
||||
SJSON = "sjson.json:sjson:jar:0.3"
|
||||
|
||||
Project.local_task "run"
|
||||
|
||||
desc "Akka Chat Sample Module"
|
||||
define "akka-sample-chat" do
|
||||
project.version = VERSION_NUMBER
|
||||
project.group = GROUP
|
||||
|
||||
compile.with AKKA, CONFIGGY
|
||||
|
||||
p artifact(MULTIVERSE).to_s
|
||||
|
||||
package(:jar)
|
||||
|
||||
task "run" do
|
||||
Java.java "scala.tools.nsc.MainGenericRunner",
|
||||
:classpath => [ compile.dependencies, compile.target,
|
||||
ASPECTJ, COMMONS_IO, JACKSON, NETTY, MULTIVERSE, PROTOBUF, REDIS,
|
||||
SBINARY, SJSON],
|
||||
:java_args => ["-server"]
|
||||
end
|
||||
end
|
||||
|
|
@ -1,50 +0,0 @@
|
|||
Guice Integration
|
||||
=================
|
||||
|
||||
Module stability: **STABLE**
|
||||
|
||||
All Typed Actors support dependency injection using `Guice <http://code.google.com/p/google-guice/>`_ annotations (such as ‘@Inject’ etc.).
|
||||
The ‘TypedActorManager’ class understands Guice and will do the wiring for you.
|
||||
|
||||
External Guice modules
|
||||
----------------------
|
||||
|
||||
You can also plug in external Guice modules and have not-actors wired up as part of the configuration.
|
||||
Here is an example:
|
||||
|
||||
.. code-block:: java
|
||||
|
||||
import static akka.config.Supervision.*;
|
||||
import static akka.config.SupervisorConfig.*;
|
||||
|
||||
TypedActorConfigurator manager = new TypedActorConfigurator();
|
||||
|
||||
manager.configure(
|
||||
new AllForOneStrategy(new Class[]{Exception.class}, 3, 1000),
|
||||
new SuperviseTypedActor[] {
|
||||
new SuperviseTypedActor(
|
||||
Foo.class,
|
||||
FooImpl.class,
|
||||
temporary(),
|
||||
1000),
|
||||
new SuperviseTypedActor(
|
||||
Bar.class,
|
||||
BarImpl.class,
|
||||
permanent(),
|
||||
1000)
|
||||
})
|
||||
.addExternalGuiceModule(new AbstractModule() {
|
||||
protected void configure() {
|
||||
bind(Ext.class).to(ExtImpl.class).in(Scopes.SINGLETON);
|
||||
}})
|
||||
.configure()
|
||||
.inject()
|
||||
.supervise();
|
||||
|
||||
Retrieve the external Guice dependency
|
||||
--------------------------------------
|
||||
|
||||
The external dependency can be retrieved like this:
|
||||
`<code format="java">`_
|
||||
Ext ext = manager.getExternalDependency(Ext.class);
|
||||
`<code>`_
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
Logging
|
||||
=======
|
||||
|
||||
Logging has been removed. See the `Event Handler <event-handler>`_.
|
||||
|
|
@ -1,41 +0,0 @@
|
|||
Akka Servlet
|
||||
============
|
||||
|
||||
=
|
||||
|
||||
Module stability: **STABLE**
|
||||
|
||||
Akka has a servlet; ‘se.scalablesolutions.akka.comet.AkkaServlet’ that can use to deploy your Akka-based application in an external Servlet container. All you need to do is to add the servlet to the ‘web.xml’, set ‘$AKKA_HOME’ to the root of the distribution (needs the ‘$AKKA_HOME/config/*’ files) and add the JARs in the ‘$AKKA_HOME/lib’ to your classpath (or put them in the ‘WEB-INF/lib’ directory in the WAR file).
|
||||
|
||||
Also, you need to add the Akka initialize/cleanup listener in web.xml
|
||||
|
||||
.. code-block:: xml
|
||||
|
||||
<web-app>
|
||||
...
|
||||
<listener>
|
||||
<listener-class>se.scalablesolutions.akka.servlet.Initializer</listener-class>
|
||||
</listener>
|
||||
...
|
||||
</web-app>
|
||||
|
||||
And to support REST actors and/or comet actors, you need to add the following servlet declaration:
|
||||
|
||||
`<code format="xml">`_
|
||||
<web-app>
|
||||
...
|
||||
<servlet>
|
||||
<servlet-name>Akka</servlet-name>
|
||||
<!-- Both Comet + REST -->
|
||||
<servlet-class>se.scalablesolutions.akka.comet.AkkaServlet</servlet-class>
|
||||
<!-- Or if you don't want to use comet, but only REST -->
|
||||
<servlet-class>se.scalablesolutions.akka.rest.AkkaServlet</servlet-class>
|
||||
</servlet>
|
||||
<servlet-mapping>
|
||||
<url-pattern>*</url-pattern>
|
||||
<servlet-name>Akka</servlet-name>
|
||||
</servlet-mapping>
|
||||
...
|
||||
</web-app>
|
||||
|
||||
`<code>`_
|
||||
|
|
@ -1,65 +0,0 @@
|
|||
Akka STM
|
||||
========
|
||||
|
||||
The Akka Software Transactional Memory implementation
|
||||
|
||||
**Read consistency**
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Read consistency is that all value TODO???
|
||||
|
||||
**Read consistency and MVCC**
|
||||
*****************************
|
||||
|
||||
A lot of STM (like the Clojure STM) implementations are Multi Version Concurrency Control (MVCC) based (TL2 of david dice could be seen as MVCC).
|
||||
|
||||
To provide read consistency, every ref is augmented with a version field (a long). There also is a logical clock (an AtomicLong for instance) that is incremented every time a transaction does a commit (there are some optimizations) and on all refs written, the version of the ref is updated to this new clock value.
|
||||
|
||||
If a transaction begins, it reads the current version of the clock and makes sure that the version of the refs it reads, are equal or lower than the version of the transaction. If the transaction encounters a ref with a higher value, the transaction is aborted and retried.
|
||||
|
||||
MVCC STM’s are relatively simple to write and have some very nice properties:
|
||||
|
||||
- readers don’t block writers
|
||||
- writers don’t block readers
|
||||
- persistent data-structures are very easy to write since a log can be added to each ref containing older versions of the data
|
||||
|
||||
The problem with MVCC however is that the central clock forms a contention point that makes independent transactional data-structures not linearly scalable. TODO: give example of scalability with MVCC.
|
||||
|
||||
So even if you have 2 Threads having their private transactional Ref (so there is no visible contention), underwater the transaction still are going to contend for the clock.
|
||||
|
||||
**Read consistency and the Akka STM**
|
||||
*************************************
|
||||
|
||||
The AkkaSTM (that is build on top of the Multiverse 0.7 STM) and from Akka 1.1 it doesn’t use a MVCC based implementation because of the scalability limiting central clock.
|
||||
|
||||
It uses 2 different mechanisms:
|
||||
1) For very short transactions it does a full conflict scan every time a new ref is read. Doing a full conflict scan sounds expensive, but it only involves volatile reads.
|
||||
2) For longer transactions it uses semi visible reads. Every time a read is done, the surplus of readers is incremented and stored in the ref. Once the transaction aborts or commits, the surplus is lowered again. If a transaction does an update, and sees that there is a surplus of readers, it increments a conflict counter. This conflict counter is checked every time a transaction reads a new ref. If it hasn’t changed, no full conflict scan is needed. If it has changed, a full conflict scan is required. If a conflict is detected, the transaction is aborted and retried. This technique is called a semi visible read (we don’t know which transactions are possibly going to encounter a conflict, but we do know if there is at least one possible conflict).
|
||||
|
||||
There are 2 important optimizations to this design:
|
||||
|
||||
- Eager full conflict scan
|
||||
- Read biases refs
|
||||
|
||||
**Eager full conflict scan**
|
||||
****************************
|
||||
|
||||
The reasons why short transactions always do a full conflict scan is that doing semi visible reads, relies on doing more expensive synchronization operations (e.g. doing a CAS to increase the surplus of readers, or doing a CAS to decrease it).
|
||||
|
||||
**Read biased vs update biased.**
|
||||
*********************************
|
||||
|
||||
The problem with semi visible reads is that certain structures (e.g. the root of a tree) can form a contention point (because of the arrives/departs) even though it mostly is read. To reduce contention, a ref can become read biased after a certain number of reads by transactions that use semi visible reads is done. Once it has become read biased, no arrives and departs are required any more, but once the Ref is updated it will always increment the conflict counter because it doesn’t know if there are any conflicting readers.
|
||||
|
||||
TODO:
|
||||
|
||||
- Visible reads, semi visible reads
|
||||
- Read tracking
|
||||
|
||||
- strict isolation
|
||||
- eager conflict detection
|
||||
- deferred write, no dirty read possible
|
||||
|
||||
- isolation level
|
||||
- optimistic
|
||||
- various levels of pessimistic behavior
|
||||
|
|
@ -1,55 +0,0 @@
|
|||
Testing of Akka
|
||||
===============
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
Testing concurrent code using time-outs (like Thread.sleep(..)) is usually a bad idea since it is both slow and error-prone. There are some frameworks that can help, some are listed below.
|
||||
|
||||
Testing Actor Interaction
|
||||
=========================
|
||||
|
||||
For Actor interaction, making sure certain message arrives in time etc. we recommend you use Akka's built-in `TestKit <testkit>`_. If you want to roll your own, you will find helpful abstractions in the `java.util.concurrent` package, most notably `BlockingQueue` and `CountDownLatch`.
|
||||
|
||||
Unit testing of Actors
|
||||
======================
|
||||
|
||||
If you need to unit test your actors then the best way to do that would be to decouple it from the Actor by putting it in a regular class/trait, test that, and then mix in the Actor trait when you want to create actors. This is necessary since you can't instantiate an Actor class directly with 'new'. But note that you can't test Actor interaction with this, but only local Actor implementation. Here is an example:
|
||||
|
||||
.. code-block:: scala
|
||||
|
||||
// test this
|
||||
class MyLogic {
|
||||
def blabla: Unit = {
|
||||
...
|
||||
}
|
||||
}
|
||||
|
||||
// run this
|
||||
actorOf(new MyLogic with Actor {
|
||||
def receive = {
|
||||
case Bla => blabla
|
||||
}
|
||||
})
|
||||
|
||||
...or define a non-anonymous MyLogicActor class.
|
||||
|
||||
Akka Expect
|
||||
===========
|
||||
|
||||
Expect mimic for testing Akka actors.
|
||||
|
||||
`<https://github.com/joda/akka-expect>`_
|
||||
|
||||
Awaitility
|
||||
==========
|
||||
|
||||
Not a Akka specific testing framework but a nice DSL for testing asynchronous code.
|
||||
Scala and Java API.
|
||||
|
||||
`<http://code.google.com/p/awaitility/>`_
|
||||
|
||||
ScalaTest Conductor
|
||||
===================
|
||||
|
||||
`<http://www.scalatest.org/scaladoc/doc-1.0/org/scalatest/concurrent/Conductor.html>`_
|
||||
|
|
@ -1,138 +0,0 @@
|
|||
Ray Roestenburg's example code from `his blog <http://roestenburg.agilesquad.com/2011/02/unit-testing-akka-actors-with-testkit_12.html>`_.
|
||||
`<code format="scala">`_
|
||||
package unit.akka
|
||||
|
||||
import org.scalatest.matchers.ShouldMatchers
|
||||
import org.scalatest.{WordSpec, BeforeAndAfterAll}
|
||||
import akka.actor.Actor._
|
||||
import akka.util.duration._
|
||||
import akka.util.TestKit
|
||||
import java.util.concurrent.TimeUnit
|
||||
import akka.actor.{ActorRef, Actor}
|
||||
import util.Random
|
||||
|
||||
/**
|
||||
* a Test to show some TestKit examples
|
||||
*/
|
||||
|
||||
class TestKitUsageSpec extends WordSpec with BeforeAndAfterAll with ShouldMatchers with TestKit {
|
||||
val echoRef = actorOf(new EchoActor).start()
|
||||
val forwardRef = actorOf(new ForwardingActor(testActor)).start()
|
||||
val filterRef = actorOf(new FilteringActor(testActor)).start()
|
||||
val randomHead = Random.nextInt(6)
|
||||
val randomTail = Random.nextInt(10)
|
||||
val headList = List().padTo(randomHead, "0")
|
||||
val tailList = List().padTo(randomTail, "1")
|
||||
val seqRef = actorOf(new SequencingActor(testActor, headList, tailList)).start()
|
||||
|
||||
override protected def afterAll(): scala.Unit = {
|
||||
stopTestActor
|
||||
echoRef.stop()
|
||||
forwardRef.stop()
|
||||
filterRef.stop()
|
||||
seqRef.stop()
|
||||
}
|
||||
|
||||
"An EchoActor" should {
|
||||
"Respond with the same message it receives" in {
|
||||
within(100 millis) {
|
||||
echoRef ! "test"
|
||||
expectMsg("test")
|
||||
}
|
||||
}
|
||||
}
|
||||
"A ForwardingActor" should {
|
||||
"Forward a message it receives" in {
|
||||
within(100 millis) {
|
||||
forwardRef ! "test"
|
||||
expectMsg("test")
|
||||
}
|
||||
}
|
||||
}
|
||||
"A FilteringActor" should {
|
||||
"Filter all messages, except expected messagetypes it receives" in {
|
||||
var messages = List[String]()
|
||||
within(100 millis) {
|
||||
filterRef ! "test"
|
||||
expectMsg("test")
|
||||
filterRef ! 1
|
||||
expectNoMsg
|
||||
filterRef ! "some"
|
||||
filterRef ! "more"
|
||||
filterRef ! 1
|
||||
filterRef ! "text"
|
||||
filterRef ! 1
|
||||
|
||||
receiveWhile(500 millis) {
|
||||
case msg: String => messages = msg :: messages
|
||||
}
|
||||
}
|
||||
messages.length should be(3)
|
||||
messages.reverse should be(List("some", "more", "text"))
|
||||
}
|
||||
}
|
||||
"A SequencingActor" should {
|
||||
"receive an interesting message at some point " in {
|
||||
within(100 millis) {
|
||||
seqRef ! "something"
|
||||
ignoreMsg {
|
||||
case msg: String => msg != "something"
|
||||
}
|
||||
expectMsg("something")
|
||||
ignoreMsg {
|
||||
case msg: String => msg == "1"
|
||||
}
|
||||
expectNoMsg
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* An Actor that echoes everything you send to it
|
||||
*/
|
||||
class EchoActor extends Actor {
|
||||
def receive = {
|
||||
case msg => {
|
||||
self.reply(msg)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* An Actor that forwards every message to a next Actor
|
||||
*/
|
||||
class ForwardingActor(next: ActorRef) extends Actor {
|
||||
def receive = {
|
||||
case msg => {
|
||||
next ! msg
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* An Actor that only forwards certain messages to a next Actor
|
||||
*/
|
||||
class FilteringActor(next: ActorRef) extends Actor {
|
||||
def receive = {
|
||||
case msg: String => {
|
||||
next ! msg
|
||||
}
|
||||
case _ => None
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* An actor that sends a sequence of messages with a random head list, an interesting value and a random tail list
|
||||
* The idea is that you would like to test that the interesting value is received and that you cant be bothered with the rest
|
||||
*/
|
||||
class SequencingActor(next: ActorRef, head: List[String], tail: List[String]) extends Actor {
|
||||
def receive = {
|
||||
case msg => {
|
||||
head map (next ! _)
|
||||
next ! msg
|
||||
tail map (next ! _)
|
||||
}
|
||||
}
|
||||
}
|
||||
`<code>`_
|
||||
|
|
@ -1,49 +0,0 @@
|
|||
Actor TestKit
|
||||
=============
|
||||
|
||||
Module Stability: **In Progress**
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
Testing actors comprises several aspects, which can have different weight according to the concrete project at hand:
|
||||
* If you have a collection of actors which performs a certain function, you may want to apply defined stimuli and observe the delivery of the desired result messages to a test actor; in this case the ***TestKit*** trait will likely interest you.
|
||||
* If you encounter undesired behavior (exceptions, dead-locks) and want to nail down the cause, it might help to run the actors in question using the ***CallingThreadDispatcher***; this dispatcher is strictly less powerful than the general purpose ones, but its deterministic behavior and complete message stack can help debugging, unless your setup depends on concurrent execution for correctness.
|
||||
* For real unit tests of one actor body at a time, there soon will be a special ***TestActorRef*** which allows access to the innards and enables running without a dispatcher.
|
||||
|
||||
TestKit
|
||||
-------
|
||||
|
||||
The TestKit is a trait which you can mix into your test class to setup a test harness consisting of an test actor, which is implicitly available as sender reference, methods for querying and asserting features of messages received by said actor, and finally methods which provide a DSL for timing assertions.
|
||||
|
||||
Ray Roestenburg has written a great article on using the TestKit: `<http://roestenburg.agilesquad.com/2011/02/unit-testing-akka-actors-with-testkit_12.html>`_. Here is a short teaser:
|
||||
|
||||
.. code-block:: scala
|
||||
|
||||
class SomeSpec extends WordSpec with MustMatchers with TestKit {
|
||||
|
||||
val worker = actorOf(...)
|
||||
|
||||
"A Worker" must {
|
||||
"send timely replies" in {
|
||||
within (50 millis) {
|
||||
worker ! "some work"
|
||||
expectMsg("some result")
|
||||
expectNoMsg
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
His full example is also available `here <testkit-example>`_.
|
||||
|
||||
CallingThreadDispatcher
|
||||
-----------------------
|
||||
|
||||
This special purpose dispatcher was conceived to enable collection of the full stack trace accumulated during processing of a complete message chain. The idea is to run invocations always on the calling thread, except when the target actor is already running on the current thread; in that case it is necessary to queue the invocation and run it after the current invocation on that actor has finished processing. This design implies that any invocation which blocks waiting on some future action to be done by the current thread will dead-lock. Hence, the CallingThreadDispatcher offers strictly more possibilities to dead-lock than a standard dispatcher.
|
||||
|
||||
One nice property is that this feature can help verify that your design is dead-lock free: if you run only on this dispatcher and utilize only one thread, then a successful run implies that for the given set of inputs there cannot be a dead-lock. (This is unfortunately not a hard guarantee, as long as your actor behavior depends on the dispatcher used, e.g. you could sabotage it by explicitly dead-locking only if self.dispatcher != CallingThreadDispatcher.)
|
||||
|
||||
TestActorRef (coming soon ...)
|
||||
------------------------------
|
||||
|
||||
|
|
@ -1,7 +0,0 @@
|
|||
Tutorial: write a scalable, fault-tolerant, persistent network chat server and client (Java)
|
||||
============================================================================================
|
||||
|
||||
Here is a couple of ports of the Scala API chat sample application in the `Scala tutorial <tutorial-chat-server-scala>`_.
|
||||
|
||||
`<https://github.com/alexaverbuch/akka_chat_java>`_
|
||||
`<https://github.com/mariofusco/akkachat>`_
|
||||
Loading…
Add table
Add a link
Reference in a new issue