Request to provide concrete examples in the documentation for OBSERVE functionality

http://support.couchbase.com/tickets/2608

Customer are interested in using OBSERVE functionality to allow them to check whether items have been replicated successfully, as they are worried about unreplicated items.

https://github.com/couchbase/libcouchbase/blob/master/man/man3couchbase/lcb_observe.3couchbase.txt
has basic info on the OBSERE functionality in libcouchbase, but we need to provide concrete examples on how to check multiple keys having been replicated successfully (they do a bulk write, so should be more efficient to wait for all of them, rather than wait for them individually)

Examples provided to the customer :

You will find the below example very useful for simple operations :

https://github.com/couchbase/php-ext-couchbase/blob/master/simple_observe.c

The below example would provide more insights when you have any performance or reliability issues :

https://github.com/couchbase/php-ext-couchbase/blob/master/observe.c

The basic idea here is to constantly "poll" the keys (sleeping within a given interval) until all of them are declared as "OK". The structures involved are the "observe_expectation" (persistence/replication requirements), the "pollprefs" (i.e. timeout, interval, etc.) and the "keystate" - this keeps tabs on how the actual status of each key matches up with the specified criteria. The lcb_observe callback is called for each "status report" for each key from each server; so it is necessary to check and see if the requirements have been met during each individual update.