README.markdown in zk-0.8.9 vs README.markdown in zk-0.9.0

- old
+ new

@@ -1,13 +1,17 @@ # 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 1.2 is experimental but _should_ work). It 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) +). + This library is heavily used in a production deployment and is actively developed and maintained. Development is sponsored by [Snapfish][] and has been generously released to the Open Source community by HPDC, L.P. +[ZK::Client::Base]: http://rubydoc.info/gems/zk/ZK/Client/Base [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" @@ -26,21 +30,21 @@ [group membership]: http://zookeeper.apache.org/doc/current/recipes.html#sc_outOfTheBox [ha-config]: http://zookeeper.apache.org/doc/current/zookeeperAdmin.html#sc_CrossMachineRequirements "HA config" ## What does ZK do that the zookeeper gem doesn't? -The [zookeeper gem][] provides a low-level, cross platform library for interfacing with ZooKeeper. While it is full featured, it only handles the basic operations that the driver provides. ZK implements the majority of the [recipes][] in the ZooKeeper documentation, plus a number of other conveniences for a production environment. +The [zookeeper gem][] provides a low-level, cross platform library for interfacing with ZooKeeper. While it is full featured, it only handles the basic operations that the driver provides. ZK implements the majority of the [recipes][] in the ZooKeeper documentation, plus a number of other conveniences for a production environment. ZK aims to be to Zookeeper, as Sequel or ActiveRecord is to the MySQL or Postgres drivers (not that ZK is attempting to provide an object persistence system, but rather a higher level API that users can develop applications with). ZK provides: * a robust lock implementation (both shared and exclusive locks) * a leader election implementation with both "leader" and "observer" roles * a higher-level interface to the ZooKeeper callback/watcher mechanism than the [zookeeper gem][] provides * a simple threadpool implementation * a bounded, dynamically-growable (threadsafe) client pool implementation * a recursive Find class (like the Find module in ruby-core) -* unix-like rm\_rf and mkdir\_p methods (useful for functional testing) +* unix-like rm\_rf and mkdir\_p methods * an extension for the [Mongoid][] ORM to provide advisory locks on mongodb records In addition to all of that, I would like to think that the public API the ZK::Client provides is more convenient to use for the common (synchronous) case. For use with [EventMachine][] there is [zk-eventmachine][] which provides a convenient API for writing evented code that uses the ZooKeeper server. [recipes]: http://zookeeper.apache.org/doc/current/recipes.html @@ -50,23 +54,28 @@ ## Caveats ZK strives to be a complete, correct, and convenient way of interacting with ZooKeeper. There are a few weak points in the implementation: +* Starting with 0.9 there is only *one* event dispatch thread (in 0.8 there are 5). It is *very important* that you don't block the event delivery thread. + +* If you're not familiar with developing solutions with zookeeper, you should read about [sessions][] and [watches][] in the Programmer's Guide. Even if you *are* familiar, you should probably go read it again. + +* It is very important that you not ignore connection state events if you're using watches. + * _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] is currently being developed and 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). -* I am currently in the process of cleaning up the API documentation and converting it to use [YARD][]. - [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/ -[dev/yard]: https://github.com/slyphon/zk/tree/dev%2Fyard +[sessions]: http://zookeeper.apache.org/doc/current/zookeeperProgrammers.html#ch_zkSessions +[watches]: http://zookeeper.apache.org/doc/r3.3.5/zookeeperProgrammers.html#ch_zkWatches ## Dependencies * The [slyphon-zookeeper gem][szk-gem] ([repo][szk-repo], branch with Gemfile [here][szk-repo-bundler]), which adds JRuby compatibility and a full suite of tests to the excellent [twitter/zookeeper][] project. _(I'm hoping to get this merged upstream, but it's a large change and, you know, people have day jobs)_. @@ -76,13 +85,13 @@ [szk-repo]: https://github.com/slyphon/zookeeper/tree/dev/xplatform [szk-repo-bundler]: https://github.com/slyphon/zookeeper/tree/dev/gemfile/ [szk-jar-gem]: https://rubygems.org/gems/slyphon-zookeeper_jar [szk-jar-repo]: https://github.com/slyphon/zookeeper_jar -### Related Projects +## Contacting the author -There are a few related projects that extend ZK. +* Send me a github message (slyphon) +* I'm usually hanging out in IRC on freenode.net in #ruby-lang and in #zookeeper +* if you really want to, you can also reach me via twitter [@slyphon][] -* [ZK::Znode][]: a simple ORM to provide ActiveModel semantics around znodes. While still in early development, may also be a useful example of how to use ZK. - -[ZK::Znode]: https://github.com/slyphon/zk-znode +[@slyphon]: https://twitter.com/#!/slyphon