Re: [OB] Add cleanup, source.c

["Michael Snyder" <msnyder@sonic.net>]

> We're both right.  Cleanups do get discarded, and cleanups that aren't
> discarded are called at the top level.  Every cleanup I've written
> since I started working on GDB at 2001 has been freed locally rather
> than at the top level, though.  I think it's very confusing if the
> cleanups are not locally paired.
>
> From gdbint.texinfo:
>
>    Your function should explicitly do or discard the cleanups it
> creates.  Failing to do this leads to non-deterministic behavior since
> the caller will arbitrarily do or discard your functions cleanups.
> This need leads to two common cleanup styles.

Yeah, that text was written by Andrew in 2003.  Before that we
had some text written by Eli in about 2001, also saying that you
should call do_cleanups.

<ahem>
Don't mean to be a curmudgeon, but I go back way before that.  ;-)

Here's how version 1.1 of the document read:

@section Cleanups

Cleanups are a structured way to deal with things that need to be done
later.  When your code does something (like @code{malloc} some memory,
or open a file) that needs to be undone later (e.g. free the memory or
close the file), it can make a cleanup.  The cleanup will be done at
some future point: when the command is finished, when an error occurs,
or when your code decides it's time to do cleanups.

You can also discard cleanups, that is, throw them away without doing
what they say.  This is only done if you ask that it be done.

Syntax:

@table @code

@item struct cleanup *@var{old_chain};
Declare a variable which will hold a cleanup chain handle.

@item @var{old_chain} = make_cleanup (@var{function}, @var{arg});
Make a cleanup which will cause @var{function} to be called with
@var{arg} (a @code{char *}) later.  The result, @var{old_chain}, is a
handle that can be passed to @code{do_cleanups} or
@code{discard_cleanups} later.  Unless you are going to call
@code{do_cleanups} or @code{discard_cleanups} yourself, you can ignore
the result from @code{make_cleanup}.