README.markdown in zk-1.0.0 vs README.markdown in zk-1.1.0
- old
+ new
@@ -1,7 +1,9 @@
# ZK
+[](http://travis-ci.org/slyphon/zk)
+
ZK is a high-level interface to the Apache [ZooKeeper][] server. It is based on the [zookeeper gem][] which is a multi-Ruby low-level driver. Currently MRI 1.8.7, 1.9.2, 1.9.3, and JRuby are supported, rubinius 2.0.testing is supported-ish (it's expected to work, but upstream is unstable, so YMMV).
ZK is licensed under the [MIT][] license.
The key place to start in the documentation is with ZK::Client::Base ([rubydoc.info][ZK::Client::Base], [local](/docs/ZK/Client/Base)).
@@ -14,52 +16,70 @@
[ZooKeeper]: http://zookeeper.apache.org/ "Apache ZooKeeper"
[zookeeper gem]: https://github.com/slyphon/zookeeper "slyphon-zookeeper gem"
[MIT]: http://www.gnu.org/licenses/license-list.html#Expat "MIT (Expat) License"
[Snapfish]: http://www.snapfish.com/ "Snapfish"
-## New in 1.0 !! ##
+## New in 1.1 !! ##
+* NEW! Thread-per-Callback event delivery model! [Read all about it!](https://github.com/slyphon/zk/wiki/EventDeliveryModel). Provides a simple, sane way to increase the concurrency in your ZK-based app while maintaining the ordering guarantees ZooKeeper makes. Each callback can perform whatever work it needs to without blocking other callbacks from receiving events. Inspired by [Celluloid's](https://github.com/celluloid/celluloid) actor model.
+
+* Use the [zk-server](https://github.com/slyphon/zk-server) gem to run a standalone ZooKeeper server for tests (`rake SPAWN_ZOOKEEPER=1`). Makes live-fire testing of any project that uses ZK easy to run anywhere!
+
+## New in 1.0 ##
+
* Threaded client (the default one) will now automatically reconnect (i.e. `reopen()`) if a `SESSION_EXPIRED` or `AUTH_FAILED` event is received. Thanks to @eric for pointing out the _nose-on-your-face obviousness_ and importance of this. If users want to handle these events themselves, and not automatically reopen, you can pass `:reconnect => false` to the constructor.
* allow for both :sequence and :sequential arguments to create, because I always forget which one is the "right one"
* add zk.register(:all) to recevie node updates for all nodes (i.e. not filtered on path)
-* add 'interest' feature to zk.register, now you can indicate what kind of events should be delivered to the given block (previously you had to do that filtering inside the block). The default behavior is still the same, if no 'interest' is given, then all event types for the given path will be delivered to that block.
+* add 'interest' feature to zk.register, now you can indicate what kind of events should be delivered to the given block (previously you had to do that filtering inside the block). The default behavior is still the same, if no 'interest' is given, then all event types for the given path will be delivered to that block.
- zk.register('/path', :created) do |event|
- # event.node_created? will always be true
- end
+```ruby
+zk.register('/path', :created) do |event|
+ # event.node_created? will always be true
+end
- # or multiple kinds of events
+# or multiple kinds of events
- zk.register('/path', [:created, :changed]) do |event|
- # (event.node_created? or event.node_changed?) will always be true
- end
+zk.register('/path', [:created, :changed]) do |event|
+ # (event.node_created? or event.node_changed?) will always be true
+end
+# this will, however, be changed in 1.1 to (backwards compatible, with a deprecation warning)
+
+zk.register('/path', :only => :created) do |event|
+end
+
+```
+
* create now allows you to pass a path and options, instead of requiring the blank string
- zk.create('/path', '', :sequential => true)
+```ruby
+zk.create('/path', '', :sequential => true)
- # now also
+# now also
- zk.create('/path', :sequential => true)
+zk.create('/path', :sequential => true)
+```
* fix for shutdown: close! called from threadpool will do the right thing
* Chroot users rejoice! By default, ZK.new will create a chrooted path for you.
- ZK.new('localhost:2181/path', :chroot => :create) # the default, create the path before returning connection
+```ruby
+ZK.new('localhost:2181/path', :chroot => :create) # the default, create the path before returning connection
- ZK.new('localhost:2181/path', :chroot => :check) # make sure the chroot exists, raise if not
+ZK.new('localhost:2181/path', :chroot => :check) # make sure the chroot exists, raise if not
- ZK.new('localhost:2181/path', :chroot => :do_nothing) # old default behavior
+ZK.new('localhost:2181/path', :chroot => :do_nothing) # old default behavior
- # and, just for kicks
-
- ZK.new('localhost:2181', :chroot => '/path') # equivalent to 'localhost:2181/path', :chroot => :create
+# and, just for kicks
+ZK.new('localhost:2181', :chroot => '/path') # equivalent to 'localhost:2181/path', :chroot => :create
+```
+
* Most of the event functionality used is now in a ZK::Event module. This is still mixed into the underlying slyphon-zookeeper class, but now all of the important and relevant methods are documented, and Event appears as a first-class citizen.
* Support for 1.8.7 WILL BE *DROPPED* in v1.1. You've been warned.
## What is ZooKeeper good for?
@@ -113,12 +133,10 @@
* _ACLS: HOW DO THEY WORK?!_ ACL support is mainly faith-based now. I have not had a need for ACLs, and the authors of the upstream [twitter/zookeeper][] code also don't seem to have much experience with them/use for them (purely my opinion, no offense intended). If you are using ACLs and you find bugs or have suggestions, I would much appreciate feedback or examples of how they *should* work so that support and tests can be added.
* ZK::Client supports asynchronous calls of all basic methods (get, set, delete, etc.) however these versions are kind of inconvenient to use. For a fully evented stack, try [zk-eventmachine][], which is designed to be compatible and convenient to use in event-driven code.
-* ZooKeeper "chroot" [connection syntax][chroot] should work for most cases. Right now we require that the root path exist before the chrooted client is used, but that may change [in the near future](https://github.com/slyphon/zk/issues/7).
-
[twitter/zookeeper]: https://github.com/twitter/zookeeper
[async-branch]: https://github.com/slyphon/zk/tree/dev%2Fasync-conveniences
[chroot]: http://zookeeper.apache.org/doc/current/zookeeperProgrammers.html#ch_zkSessions
[YARD]: http://yardoc.org/
[sessions]: http://zookeeper.apache.org/doc/current/zookeeperProgrammers.html#ch_zkSessions
@@ -131,10 +149,10 @@
* [DCell](https://github.com/celluloid/dcell): Distributed ruby objects, built on top of the super cool [Celluloid](https://github.com/celluloid/celluloid) framework.
## Dependencies
-* The [slyphon-zookeeper gem][szk-gem] ([repo][szk-repo]), which adds JRuby compatibility and a full suite of tests to the excellent [twitter/zookeeper][] project.
+* The [slyphon-zookeeper gem][szk-gem] ([repo][szk-repo]).
* For JRuby, the [slyphon-zookeeper\_jar gem][szk-jar-gem] ([repo][szk-jar-repo]), which just wraps the upstream zookeeper driver jar in a gem for easy installation
[szk-gem]: https://rubygems.org/gems/slyphon-zookeeper
[szk-repo]: https://github.com/slyphon/zookeeper