Asynchronous Interface¶
The asynchronous interface to the SDK is a work in progress, and is currently intended to be used by integrators into higher level async wrappers. See the txcouchbase package for an example.
This document largely explains the current internals of how the Couchbase async module works in a lower level. For a higher level overview, see: http://blog.couchbase.com/python-sdk-and-twisted
Key-Value Interface¶
The Key-Value interface of the async subsystem functions as closely as possible like its synchronous counterpart. The primary difference is that where the synchronous interface would return an instance of a Result or a MultiResult, the asynchronous interface returns an AsyncResult object.
The AsyncResult object contains fields for two callbacks which are invoked when the result is ready. One is the callback field which is called with a Result or MultiResult upon success, and the other is the errback field which is invoked with an exception object upon error.
The semantics of when an exception is passed follows the rules of the quiet parameter just like the synchronous API.
- class couchbase.result.AsyncResult¶
- class couchbase.async.bucket.AsyncBucket¶
Views Interface¶
Different from the key-value interface, the synchronous view API returns a View object which is itself an iterator which yields results. Because this is a synchronous API, the iterator interface must be replaced with a class interface which must be subclassed by a user.
- class couchbase.async.view.AsyncViewBase¶
I/O Interface¶
The async API is divided into several sections. In order to have an async client which interacts with other async libraries and frameworks, it is necessary to make the Couchbase extension aware of that environment. To this end, the IOPS interface is provided. The IOPS API is entirely separate from the key-value API and should be treated as belonging to a different library. It is simply the extension’s I/O abstraction.
- class couchbase.iops.base.Event¶
This class represents an Event. This concept should be familiar to the intended audience, who should be familiar with event loops and their terminology. It represents a certain event in the future, which shall be triggered either by something happening or by the passage of time.
When said event takes place, the object should be signalled via the ready() method.
- class couchbase.iops.base.IOEvent¶
A subclass of Event, this represents a socket. Events applied to this socket are triggered when the socket becomes available for reading or writing.
- class couchbase.iops.base.IOPS¶
Action Constants¶
- couchbase.iops.base.PYCBC_EVACTION_WATCH¶
Action indicating the specific event should be added to the event loop’s “watcher” list, and should be have its ready() method called when the IO implementation has detected the specific event is ready
- couchbase.iops.base.PYCBC_EVACTION_UNWATCH¶
Action indicating that the specific object should not be notified when the IO state changes. This is typically done by removing it from the watcher list
- couchbase.iops.base.PYCBC_EVACTION_CLEANUP¶
Action to permanently erase any references to this event
IO Event Constants¶
- couchbase.iops.base.LCB_READ_EVENT¶
IO Flag indicating that this event should be notified on file readbility
- couchbase.iops.base.LCB_WRITE_EVENT¶
IO flag indicating that this event should be notified on file writeability
- couchbase.iops.base.LCB_RW_EVENT¶
Equivalent to LCB_READ_EVENT|LCB_WRITE_EVENT