diff options
author | Jakob Odersky <jodersky@gmail.com> | 2015-05-25 11:41:19 +0200 |
---|---|---|
committer | Jakob Odersky <jodersky@gmail.com> | 2015-05-25 11:41:19 +0200 |
commit | f88836c5559c5ba9efebcdd3b78c1901e3d851d6 (patch) | |
tree | 1b77c57805c9ccebdb7031804d29ef89b44615d9 /Documentation/watching.md | |
parent | 7db412df69ded4f035cfa21c5a49451d31877d23 (diff) | |
download | akka-serial-f88836c5559c5ba9efebcdd3b78c1901e3d851d6.tar.gz akka-serial-f88836c5559c5ba9efebcdd3b78c1901e3d851d6.tar.bz2 akka-serial-f88836c5559c5ba9efebcdd3b78c1901e3d851d6.zip |
add documentation on watchers
Diffstat (limited to 'Documentation/watching.md')
-rw-r--r-- | Documentation/watching.md | 47 |
1 files changed, 47 insertions, 0 deletions
diff --git a/Documentation/watching.md b/Documentation/watching.md new file mode 100644 index 0000000..8735a46 --- /dev/null +++ b/Documentation/watching.md @@ -0,0 +1,47 @@ +# Watching Ports +As of version 2.2.0, flow can watch directories for new files. On most unix systems this can be used for watching for new serial ports in `/dev`. +Watching happens through a message-based, publish-subscribe protocol as explained in the sections below. + +## Subscribe +A client actor may watch, i.e subscribe to notifications on, a directory by sending a `Watch` command to the serial manager. + +Should an error be encountered whilst trying to obtain the watch, the manager will respond with a `CommandFailed` message. +Otherwise, the client may be considered "subscribed" to the directory and the serial manager will thenceforth notify +the client on new files. + +```scala +IO(Serial) ! Watch(directory = "/dev", skipInitial = true) + +def receive = { + case CommandFailed(w: Watch, reason) => + println(s"Cannot obtain a watch on ${w.directory}: ${reason.getMessage}") +} + +``` + +Note the second argument `skipInitial` of the watch command. This flag specifies if the client should not be notified of files already present +during the manager's reception of the watch command. + +## Notifications +Whilst subscribed to a directory, a client actor is informed of any new files in said directory by receiving +`Connected` messages from the manager. + +```scala +def receive = { + case Connected(port) if port matches "/dev/ttyUSB.*" => + // do something with the available port, e.g. + // IO(Serial) ! Open(port, settings) +} +``` + +## Unsubscribe +Unsubscribing from events on a directory happens by sending an `Unsubscribe` message to the serial manager. + +```scala +IO(Serial) ! Unwatch(directory = "/dev") +``` + +Note that the manager has a deathwatch on every subscribed client. Hence should a client die, underlying resources will be freed. + +# Requirements +Flow uses java's `WatchService`s under the hood, therefore a java runtime of at least 1.7 is required. |