Common Utilities for C C++ SDK functionality

Version 2 by mnunberg
on Mar 25, 2013 15:28.

compared with
Current by mnunberg
on Apr 14, 2013 11:18.

This line was removed.
This word was removed. This word was added.
This line was added.

Changes (3)

View Page History
As it stands, _libcouchbase_ is primarily the protocol layer (both memcached and HTTP) for talking to the Couchbase server; however there are some higher level operations which may need further common handling:

h1. Functional Requirements/Specifications

h2. Durability API

h3. API Inputs

The view API inputs consist of feeding string data into an opaque parser context. The parser context will also be set up with callbacks which will be invoked upon receipt of each parsed view row, or on a parse error.

* Opaque parse context (API function to initialize/create this)
* Error callback
* Row callback

h3. API Output

* Row Callback
** Will contain a single row only
* Error Callback
** Will contain an error code, as well as the raw text for the response
* Parse context
** Will contain non-row meta-data returned in the view result, as well as any HTTP metadata (such as the return code)

h3. Usage Model

The usage model for the incremental row parsing is slightly more involved as it requires setting up two different callbacks. Generally speaking however, the receipt of each view row is to follow the semantics of responses for something like a multi-get, in that a new callback is invoked for each row.

One is required to create a "view row parser context" (which may be re-used) which allocates the necessary handles for the parser object. Then incoming data is fed into the buffer (a convenience HTTP callback may be provided to allow for this boilerplate to be performed transparently). When sufficient data has been fed and at least one row has been internally delimited by the parser, the row callback is invoked. If an error occurs during parsing, the error callback is invoked.

h3. Example Code


h2. Common Flag/Datatype handling

 This may be a simple set of macros to set/unset flags

h2. C+\+ Wrappers

It might be prudent to also create proper C+\+ wrappers around libcouchbase, so that one may be able to do something like:

LCB::Result& result = lcb->get("foo");

h1. Deployment/Distribution

It has been recommended in the past that this be provided as an external library which will be called _lcb_util_. While the matter of whether this functionality be included inside an 'lcb_util' or integrated into libcouchbase itself is important, we will discuss several logistics, and pros/cons of both.

h2. As a Standalone Library

Having an _lcb_util_ would allow a different branch of development to proceed for somewhat higher level functions from which all SDKs can develop with a guarantee that this would not hinder and/or affect core protocol/network handling functionality.

The drawbacks involve the complexity of deployment (the goal is really to make most SDKs use these common utility functions which may be tested) - as such, it would now require the user to install two libraries instead of one - a detail which we may not wish to bother the user with.

Additionally, it would require modularization of libcouchbase's testing framework so that the API functions within this utility library can be tested. If the new functionality will be part of the SDKs, it will need to receive the same testing coverage and frequency as libcouchbase itself. This would require deploying libcouchbase's test functionality to an API level so that it may be used by the new utilities.

h2. As Part of libcouchbase

Having this functionality included within libcouchbase would avoid the deployment issues mentioned above. It would also allow for better optimization and integration when modifications to libcouchbase itself are needed (rather than requiring modifications to the API itself).

Additionally, the complexities in testing are reduced as the functionality of these utility/extension features are tested whenever libcouchbase itself is tested.

The drawbacks involve slowdowns in modification and development, with changes to the utility methods requiring the same level of scrutiny and release frequency as libcouchbase itself.