[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

API docs and pool usage (was: Re: svn commit: r14557 - in trunk/subversion: clients/cmdline include libsvn_client libsvn_diff svnlook)

From: Peter N. Lundblad <peter_at_famlundblad.se>
Date: 2005-05-07 13:11:29 CEST

(I'm changing the subject line, since the API question below is more
important than the actual commit.)

On Fri, 6 May 2005, Philip Martin wrote:

> "Peter N. Lundblad" <peter@famlundblad.se> writes:
> > On Wed, 4 May 2005, [UTF-8] Branko ─^Libej wrote:
> >
> >> Philip Martin wrote:
> >>
> >> >Why the apr_pstrdup?
> >> >
> >> Yes, I just noticed this and asked myself the same thing. There's no
> >> need to copy this string around.
> >>
> > Because that's what the docstring says it does. So, why did he write the
> > docstring that way? Because I think it is consistent with what we do
> > elsewhere.
> I'm aware that input strings are sometimes duplicated before being
> returned, but that's to avoid making assumptions about the lifetime of
> the inputs. That consideration doesn't apply in this case, so the
> consistency argument doesn't seem to apply.
We have lots of API routines that returns strings "allocated in @a pool".
So, I think we have two questions here:
- What should the docstrin gsay
- if the docstring says "allocated in @a pool", is the function allowed to
  return a statically allocated string?

For the first question, I think it is fine to allow the function to
allocate its return value out of @a pool. In general, returning statically
allocated strings is not a good idea IMO. Consider what happens if we want
to be able to change this value at runtime in the future? We could say
something like "Returns a statically allocated string, or a string
allocated in @a pool" if there was a compelling reason to do so. For cod
ehtat is used inside inner loops, I think this micro-optimization could be
useful. OK, you never know where your APIs will be used, but I can't
imagine that allocating memory out of a pool and copying a string,
typically shorter than 30 bytes, to be a bottleneck in any reasonable
scenario. Philip, if you want the docstring to be changed, please say so
explicitly in your next reply.

For the second question, I think the answer is "no". Here's an example:

Say we have an application plugin (for whatever application you can think
of) that uses our libraries. The app load the plugin that links to our
libs. The plugin calls an svn functiion that returns a value "allocated in
@a pool"; @a pool is controlled by the application. The plugin gives the
return value to the app, which it thinks is OK, since the alue is
allocated in a pool that the app controls. The app unloads the plugin and
then uses the data returned. Crash!

I can't say this scenario (or some variant thereof) is unreasonable and
therefore I think "allocated in @a pool" should really mean what it says.

> > Well, we could change it, but is it a big deal, really?
Presumably (answering my own question).


To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Sat May 7 13:04:17 2005

This is an archived mail posted to the Subversion Dev mailing list.

This site is subject to the Apache Privacy Policy and the Apache Public Forum Archive Policy.