You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@subversion.apache.org by Ich selbst <ic...@gmx.ch> on 2002/08/25 17:40:09 UTC
client api not optimal
Hi,
After going through the sources of Subversion I have a request for the
client api.
It now contains functions which need batons (what is a baton???) and
typedefs
from apr headers. I think that's not really good. In my opinion an api
should be
usable independently. So handling batons and structs from apr should be
handled
internally by subversion and not be needed for the client api. Best would be
an API
with functions like the command line client offers (or do you think
subversion would
ever become a success if the command line clients would ask for batons and
structs?
No! You only enter there basic 'data types' like strings and numbers).
I suggest the following changes for the client api:
- instead of notify funtions and batons just use the notify functions
- handle the apr_pool_t *pool internally
- instead of the auth_baton use 'username' and 'password' - thats more
understandable
- avoid structs for the api, use the data of the struct directly (better
usability for clients
written in managed languages like java, c#, ...)
- if you use structs for the api, declare them inside the same header as the
functions.
I know, this mail will get many comments with all the same conclusion: 'do
it yourself'.
(happens almost every time I request something). But please keep in mind
that
since you don't provide a GUI-client and expect other to write such clients
then
you have to offer a 'good' API for the clients. If everyone who wants to
write a GUI
for using Subversion needs to dig deep and deeper into the subversion source
just
to find out all the parameters of the functions offered then many will give
up
(I'm very close to it). For example: I just spent 5 hours looking for all
structures used
in the functions in svn_client.h...
kind regards,
Stefan
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: client api not optimal
Posted by Justin Erenkrantz <je...@apache.org>.
On Sun, Aug 25, 2002 at 09:25:01PM +0200, Ich selbst wrote:
> > But there are more ways to authenticate than by username and password.
> then simply provide other functions (that's called overloading) with those
> other
> authentication parameters.
You can't overload with the same function name in C. -- justin
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: client api not optimal
Posted by Ich selbst <ic...@gmx.ch>.
> An API as simple as the command-line client would be as limited as the
> command-line client: no error-handling beyond success or failure except
> by recognizing error strings (brittle); no complicated information in or
> out, such as the information required for a log message, without parsing
> strings (complicated and brittle); no fine control over what to do with
> informational output.
- didn't know that the command line client is limited...
- 'standard' ways of handling complicated information is to use 'standard'
i.e. base types like arrays of strings, ...
> Really, all you could make with an API like that is a command-line
> client, which we have, or a GUI which feels like a thin layer on top of
> a command-line client, which we don't want. For a good GUI you want
> something more structured.
agreed. But only if you want a GUI only for Subversion. Addins for IDE's
and Editors sometimes simply can't be more structured.
> The baton is a piece of data passed to the notify function. (Other APIs
> sometimes call that "userdata".) If we take out the baton, there is no
> way to get information to the notify function except through global
> variables. Global variables work fine for simple applications, but
> don't scale to the complicated ones.
ok, but then why not give a description of what the baton is about in
the description of the function? Especially if you use apr batons - its
very time consuming to look through all the header to find the declarations
of the batons and even more to find out what they are for.
>
> > - handle the apr_pool_t *pool internally
>
> This might be a good idea for libsvn_client, since the interface is very
> granular. Unfortunately, if you get an error back, the memory for that
> error comes from a pool, and we can't really "handle" that internally.
hmmm - the command line client does that.
if not: if you can't handle that internally, how can it be handled by a
client?
>
> > - instead of the auth_baton use 'username' and 'password' - thats more
> > understandable
>
> But there are more ways to authenticate than by username and password.
then simply provide other functions (that's called overloading) with those
other
authentication parameters.
>
> > - avoid structs for the api, use the data of the struct directly
>
> Glancing over svn_client, it looks we have a good reason to use
> structures in each of the places we do so. (Although I am concerned
> about the auth baton; that structure will almost certainly need to grow,
> which could affect our ABI.)
but there are programming languages which don't support structures directly.
And for those it's easier to cast 'basic' types to the required ones than
structures.
> > - if you use structs for the api, declare them inside the same header as
the
> > functions.
>
> Not really practical. And in general, if you don't understand what a
> type is, your first questions should not be "what fields does it have?"
> but "what is it for" and "how do I make and manipulate it?" Those we
> can answer without a declaration in the same header file.
that's only true if you write a GUI in C or C++. For other languages you
need to know what fields it has, what types the fields are. And if you have
structures inside structures inside structures... you spend a lot of time
doing that.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: client api not optimal
Posted by Greg Stein <gs...@lyra.org>.
On Sun, Aug 25, 2002 at 03:01:11PM -0400, Greg Hudson wrote:
>...
> > - avoid structs for the api, use the data of the struct directly
>
> Glancing over svn_client, it looks we have a good reason to use
> structures in each of the places we do so. (Although I am concerned
> about the auth baton; that structure will almost certainly need to grow,
> which could affect our ABI.)
That auth baton thing is crapola. It'll get tossed/changed when I make time
to get libsvn_auth in place. The new system should be much better for growth
and a bit more resilient to ABI changes.
Cheers,
-g
--
Greg Stein, http://www.lyra.org/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: client api not optimal
Posted by Greg Hudson <gh...@MIT.EDU>.
An API as simple as the command-line client would be as limited as the
command-line client: no error-handling beyond success or failure except
by recognizing error strings (brittle); no complicated information in or
out, such as the information required for a log message, without parsing
strings (complicated and brittle); no fine control over what to do with
informational output.
Really, all you could make with an API like that is a command-line
client, which we have, or a GUI which feels like a thin layer on top of
a command-line client, which we don't want. For a good GUI you want
something more structured.
On Sun, 2002-08-25 at 13:40, Ich selbst wrote:
> I suggest the following changes for the client api:
> - instead of notify funtions and batons just use the notify functions
The baton is a piece of data passed to the notify function. (Other APIs
sometimes call that "userdata".) If we take out the baton, there is no
way to get information to the notify function except through global
variables. Global variables work fine for simple applications, but
don't scale to the complicated ones.
> - handle the apr_pool_t *pool internally
This might be a good idea for libsvn_client, since the interface is very
granular. Unfortunately, if you get an error back, the memory for that
error comes from a pool, and we can't really "handle" that internally.
> - instead of the auth_baton use 'username' and 'password' - thats more
> understandable
But there are more ways to authenticate than by username and password.
> - avoid structs for the api, use the data of the struct directly
Glancing over svn_client, it looks we have a good reason to use
structures in each of the places we do so. (Although I am concerned
about the auth baton; that structure will almost certainly need to grow,
which could affect our ABI.)
> - if you use structs for the api, declare them inside the same header as the
> functions.
Not really practical. And in general, if you don't understand what a
type is, your first questions should not be "what fields does it have?"
but "what is it for" and "how do I make and manipulate it?" Those we
can answer without a declaration in the same header file.
> If everyone who wants to write a GUI for using Subversion needs to dig deep
> and deeper into the subversion source
Here we agree; you should not have to look at the source code to write a
client. For the most part, the combination of HACKING and the comments
in svn_client.h should make things clear enough to write code; where it
doesn't, complain specifically.
(In an ideal world, we would have more comprehensive API documentation;
perhaps a man page for each function. But what we have now isn't really
so bad.)
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: client api not optimal
Posted by Philip Martin <ph...@codematters.co.uk>.
"Ich selbst" <ic...@gmx.ch> writes:
> > Subversion depends on APR, your application is going to link against
> > APR, so using APR types doesn't seem unreasonable.
> Only if you compile the complete source of Subversion for the client. But
> I hope that there will be compiled libraries to link to for clients. And
> then
The Subversion libraries depend on APR, so you *will* have to link
against APR.
> you would need not just one but many many header files to include
> (and look through if you don't use C or C++ and can't include those headers
> directly)
If you want to use Subversion from a language that doesn't directly
support C then you will need appropriate bindings, that's how
multi-language programming works. If you use language X, where
someone else has already provided bindings, then use those. If you
use language Y, where no one has yet provided bindings, then you get
to write the bindings :-)
What so hard about searching header files anyway? One grep from the
command line (or I suppose a GUI based search for IDE people). Or set
up a TAGS file and use Emacs tags. Or whatever, just use an
appropriate tool.
>
> > [snip]
> >
> > > - instead of the auth_baton use 'username' and 'password' - thats more
> > > understandable
> >
> > When you call svn_client_checkout, say, you do not know if a username
> > or password is required. Do you intend to always prompt the user for
> > these, even if they are not required? Isn't that a little primitive?
> > The point of the auth_baton is that if the data are not required then
> > there is no need to provide them.
> I don't want the user to enter those every time, but once. And then store
> those during a whole session.
You have missed the point. Why should I enter them once if they are
not required? The auth_baton has callbacks to get the username and
password, if the auth data are not required the callbacks do not get
called and so I never enter the data. If the auth data are required,
the callbacks should request the data and cache it. That's how the
command line client does it.
--
Philip Martin
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: client api not optimal
Posted by Ich selbst <ic...@gmx.ch>.
[snip]
> You can always set the baton to NULL if you don't want to use it.
>
> Subversion depends on APR, your application is going to link against
> APR, so using APR types doesn't seem unreasonable.
Only if you compile the complete source of Subversion for the client. But
I hope that there will be compiled libraries to link to for clients. And
then
you would need not just one but many many header files to include
(and look through if you don't use C or C++ and can't include those headers
directly)
> [snip]
>
> > - instead of the auth_baton use 'username' and 'password' - thats more
> > understandable
>
> When you call svn_client_checkout, say, you do not know if a username
> or password is required. Do you intend to always prompt the user for
> these, even if they are not required? Isn't that a little primitive?
> The point of the auth_baton is that if the data are not required then
> there is no need to provide them.
I don't want the user to enter those every time, but once. And then store
those during a whole session.
And if you don't want to use those, like you mentioned above: "You
can always set the <replace baton with authentication> to NULL if
you don't want to use it.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: client api not optimal
Posted by Philip Martin <ph...@codematters.co.uk>.
"Ich selbst" <ic...@gmx.ch> writes:
> Hi,
>
> After going through the sources of Subversion I have a request for the
> client api.
> It now contains functions which need batons (what is a baton???) and
> typedefs
> from apr headers. I think that's not really good.
Nearly all C callback systems use batons, although they don't always
call them batons. If you want examples look at the XtPointer
parameter to XtAddCallback in the Xt library, the void* parameter to
pthread_create in the pthread library, the gpointer parameter to
g_signal_connect in the gtk library, etc. How else is your
application going to pass application specific data to the callback?
You can always set the baton to NULL if you don't want to use it.
Subversion depends on APR, your application is going to link against
APR, so using APR types doesn't seem unreasonable.
[snip]
> - instead of the auth_baton use 'username' and 'password' - thats more
> understandable
When you call svn_client_checkout, say, you do not know if a username
or password is required. Do you intend to always prompt the user for
these, even if they are not required? Isn't that a little primitive?
The point of the auth_baton is that if the data are not required then
there is no need to provide them.
--
Philip Martin
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: client API not optimal
Posted by Greg Stein <gs...@lyra.org>.
On Mon, Aug 26, 2002 at 05:02:29PM -0400, Greg Hudson wrote:
> Brent Matzelle wrote:
> > Unfortunately I do not have a method to abstract the notify
> > functions. Hopefully this can be worked out later.
>
> I guess the C++ way of doing this is subclassing and virtual methods.
> For instance, the class which interfaces to svn_client_update() could
> call its own update_notify() method in response to a notify_func call.
> The base implementation would do nothing; an application could subclass
> that type and override the method.
>
> Or some variation on that idea.
I would see it as the client provides a "Notified" object which has a pure
virtual interface on it. The C++ wrappers would invoke the appropriate
methods on the supplied Notified object. Thus, you could easily mix/match
notification callbacks without changing/subclassing the target object.
(this is the model that I intend to use with the Python bindings)
Cheers,
-g
--
Greg Stein, http://www.lyra.org/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: client API not optimal
Posted by Greg Hudson <gh...@MIT.EDU>.
Brent Matzelle wrote:
> Unfortunately I do not have a method to abstract the notify
> functions. Hopefully this can be worked out later.
I guess the C++ way of doing this is subclassing and virtual methods.
For instance, the class which interfaces to svn_client_update() could
call its own update_notify() method in response to a notify_func call.
The base implementation would do nothing; an application could subclass
that type and override the method.
Or some variation on that idea.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: client API not optimal
Posted by Greg Stein <gs...@lyra.org>.
On Mon, Aug 26, 2002 at 01:30:30PM +0100, Barry Scott wrote:
>...
> I agree that the learning curve to drive svn from python
> or C++ is far to steep.
The Python bindings (via SWIG) to SVN exactly mirros the SVN API. Thus, the
Python code is going to be no more easier or difficult than the C API
itself.
However, it is also important to note that it is easy to provide an
additional layer of Python code over the underlying, primitive API. For
example, see the Editor class in the svn.delta module. Or the run_app
function in svn.util.
Similar abstractions can easily be added to the FS, Repos, etc. Much like
you're adding abstractions using C++ classes, you can do the same with
Python. In fact, I expect this additional layering for all the SWIG
bindings (Python, Perl, Java, etc). Each language would create an additional
higher-level API in the style appropriate for that language.
Cheers,
-g
--
Greg Stein, http://www.lyra.org/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
RE: client API not optimal
Posted by "Brent R. Matzelle" <bm...@yahoo.com>.
--- Barry Scott <ba...@ntlworld.com> wrote:
> Stefan,
> May be the hiding of deeper internals can be done with
> the C++ API that Brent is writing.
That's the idea.
> It is quite feasible
> to lose all of the svn and apr headers from that C++ API
> using pure virtual classes and factory functions to create
> the objects. But I don't think Brent was planning to go
> that far.
So far nearly all svn and apr code is hidden by the API.
Unfortunately I do not have a method to abstract the notify
functions. Hopefully this can be worked out later.
Brent
__________________________________________________
Do You Yahoo!?
Yahoo! Finance - Get real-time stock quotes
http://finance.yahoo.com
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
RE: client API not optimal
Posted by Barry Scott <ba...@ntlworld.com>.
Stefan,
May be the hiding of deeper internals can be done with
the C++ API that Brent is writing. It is quite feasible
to lose all of the svn and apr headers from that C++ API
using pure virtual classes and factory functions to create
the objects. But I don't think Brent was planning to go
that far.
I agree that the learning curve to drive svn from python
or C++ is far to steep.
The hideous SourceSafe API is easy to use in comparison.
And perforce commands ability to output in Python
marshaled objects make automating around perforce reliable
(no parsing of the output).
Personally I'm hoping that I can run the svn command to do
all the GUI/automation that I'll need. I'm not looking
forward to learning to drive svn at its C API.
Barry
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org