Re: [PATCH 1/2] commit-slab: document clear_$slabname()

From: Jonathan Nieder <jrnieder@gmail.com>
Date: Nov 25, 2013, 20:24 UTC
Message-ID: <20131125202409.GO4212@google.com>
In-Reply-To: <7f773c5c5ea16b19840f67ba99961be132940d32.1385405977.git.tr@thomasrast.ch>

Thomas Rast wrote:

> The clear_$slabname() function was only documented by source code so
> far.  Write something about it.

Good idea.

[...]

Show 10 quoted lines

> --- a/commit-slab.h
> +++ b/commit-slab.h
> @@ -24,6 +24,10 @@
>   *   to each commit. 'stride' specifies how big each array is.  The slab
>   *   that id initialied by the variant without "_with_stride" associates
>   *   each commit with an array of one integer.
> + *
> + * - void clear_indegree(struct indegree *);
> + *
> + *   Free the slab's data structures.

Tense shift (previous descriptions were in the present tense, while this one is in the imperative).

More importantly, this doesn't answer the questions I'd have if I were in a hurry, which are what exactly is being freed (has the slab taken ownership of any memory from the user, e.g. when elemtype is a pointer?) and whether the slab needs to be init_ ed again.

Maybe something like the following would work?

	- void clear_indegree(struct indegree *);

	  Empties the slab.  The slab can be reused with the same
	  stride without calling init_indegree again or can be
	  reconfigured to a different stride by calling
	  init_indegree_with_stride.

	  Call this function before the slab falls out of scope to
	  avoid leaking memory.

Thanks, Jonathan