Re: [PATCH 3/3] Documentation: document difference between release and free

From: Patrick Steinhardt <ps@pks.im>
Date: Jul 30, 2024, 06:43 UTC
Message-ID: <ZqiLn6JR5BBf9sJU@tanuki>
In-Reply-To: <xmqqed7iwx4r.fsf@gitster.g>

On Wed, Jul 24, 2024 at 09:52:20AM -0700, Junio C Hamano wrote:

Show 18 quoted lines

> Patrick Steinhardt <ps@pks.im> writes:
> 
> > We semi-regularly have discussions around whether a function shall be
> > named `release()` or `free()`. For most of the part we use these two
> > terminologies quite consistently though:
> >
> >   - `release()` only frees internal state of a structure, whereas the
> >     structure itself is not free'd.
> >
> >   - `free()` frees both internal state and the structure itself.
> >
> > Carve out a space where we can add idiomatic names for common functions
> > in our coding guidelines. This space can get extended in the future when
> > we feel the need to document more idiomatic names.
> 
> We have _clear() in some subsystem/API.  Are we sure the listed two
> are sufficient and _clear() can be replaced with one of them
> (perhaps _release())?

I'd think that `clear()` can be replaced by `release()`, yes. But in another branch I heard the argument that `clear()` is equivalent to `release()` followed by `init()`, which I do like. The only downside is that `init()` must not allocate memory in this case, as otherwise the `clear()` function would lose the ability to release all resources associated with its structure.

Patrick