Erlang API (was Re: code style)

[Adam Kocoloski <ko...@apache.org>]

On Jan 23, 2011, at 7:40 AM, Filipe David Manana wrote:

> On Sat, Jan 22, 2011 at 10:27 AM, Benoit Chesneau <bc...@gmail.com> wrote:
>> 
>> Imo the thing we could have in view, except this plugin "support", is
>> a simple api to call any part of couchdb we need. Something as simple
>> as the HTTP api but for erlang.
>> 
>>  I'm thinking to have a couchbeam pure erlang api for example just for
>> that. It would also help us to make new HTTP layer using webmachine
>> for example or anything. fabric an hovercraft are also good
>> inspiration. I'm pretty ready to do such thing. Does it worth a thread
>> to discuss about it?
> 
> You already have that with the new replicator. It brings a module
> named "couch_api_wrap.erl". For now, it only has functions necessary
> for the replicator to operate both with local and remote databases.
> Nevertheless, it already covers a significant subset of the CouchDB API

Yes, I think it's good to have a separate discussion on this one, but I'll go ahead and toss my thoughts in here as well.  One of the things I quite like about fabric.erl as opposed to couch_api_wrap.erl is that it minimizes the use of records in the interface, e.g. it has converters to turn client-supplied proplists into internal #changes_args and #view_query_args.  I also like that it accepts iodata() for most strings instead of requiring the client to convert to binaries.  It saves some typing when interacting with BigCouch from the shell.

I think one big question for an Erlang API is whether it should require the client to manually open and close the DB.  Fabric does not impose this requirement, primarily because it doesn't make much sense in a BigCouch cluster.  There are certainly advantages to having a DB handle open, but I think many of those can be nullified by making it really cheap to open a DB.  My preference would be to make it optional, i.e. functions like update_docs would have a clause that accepts a DbName (and a user context in the options) in addition to one that accepts a #db.

> 
>> 
>> - benoît
>> 
> 
> 
> 
> -- 
> Filipe David Manana,
> fdmanana@gmail.com, fdmanana@apache.org
> 
> "Reasonable men adapt themselves to the world.
>  Unreasonable men adapt the world to themselves.
>  That's why all progress depends on unreasonable men."

Re: Erlang API (was Re: code style)

[Benoit Chesneau <bc...@gmail.com>]

On Mon, Jan 24, 2011 at 4:06 PM, Adam Kocoloski <ko...@apache.org> wrote:
> On Jan 23, 2011, at 7:40 AM, Filipe David Manana wrote:
>
>> On Sat, Jan 22, 2011 at 10:27 AM, Benoit Chesneau <bc...@gmail.com> wrote:
>>>
>>> Imo the thing we could have in view, except this plugin "support", is
>>> a simple api to call any part of couchdb we need. Something as simple
>>> as the HTTP api but for erlang.
>>>
>>>  I'm thinking to have a couchbeam pure erlang api for example just for
>>> that. It would also help us to make new HTTP layer using webmachine
>>> for example or anything. fabric an hovercraft are also good
>>> inspiration. I'm pretty ready to do such thing. Does it worth a thread
>>> to discuss about it?
>>
>> You already have that with the new replicator. It brings a module
>> named "couch_api_wrap.erl". For now, it only has functions necessary
>> for the replicator to operate both with local and remote databases.
>> Nevertheless, it already covers a significant subset of the CouchDB API
>
> Yes, I think it's good to have a separate discussion on this one, but I'll go ahead and toss my thoughts in here as well.  One of the things I quite like about fabric.erl as opposed to couch_api_wrap.erl is that it minimizes the use of records in the interface, e.g. it has converters to turn client-supplied proplists into internal #changes_args and #view_query_args.  I also like that it accepts iodata() for most strings instead of requiring the client to convert to binaries.  It saves some typing when interacting with BigCouch from the shell.
>
+1 That's indeed really convenient as a client level.

> I think one big question for an Erlang API is whether it should require the client to manually open and close the DB.  Fabric does not impose this requirement, primarily because it doesn't make much sense in a BigCouch cluster.  There are certainly advantages to having a DB handle open, but I think many of those can be nullified by making it really cheap to open a DB.  My preference would be to make it optional, i.e. functions like update_docs would have a clause that accepts a DbName (and a user context in the options) in addition to one that accepts a #db.

At least I don't think we should test if a db exists or not when we
open a db like in couch_api_wrap, rather we should make it lazy and
crash only when we call a function using the db. So we minimize call.
I'm not sure about the impact of opening/closing a db right now but I
guess that if we monitor activity of the db process it should we the
case we let a db open?

- benoît