Re: [bug-mailutils] Merging libraries (was Re: Mailutils 0.3 released)

[Sergey Poznyakoff]

> I do not quite understand the answer, your are saying you do not
> want to do this, because it is incompatible to the old way?

No, not quite so. I agree that using message_unref is a good idea
(I'd only propose to call it message_destroy for consistency).
What I meant is that its use should not be mandatory, i.e.
both of the following should be allowed:

  for (i = 0; i < count; i++) {
    mailbox_get_message(mbox, &msg);
    ...
    message_unref(msg);
  }

and

  for (i = 0; i < count; i++) {
    mailbox_get_message(mbox, &msg);
    ...
  }

The latter example will result in using more memory, however it
will be reclaimed after calling mailbox_destroy().

In short:

1) mailbox_get_message retrieves a pointer to the data allocated under
mailbox_t.

2) Calling mailbox_get_message(mbox, 2, &msg) several times is not an
error and does not result in allocating more memory. It only
increments the reference count associated with `msg'.

3) Calling message_destroy(&msg) decrements the reference count. If
the count falls to zero, it frees all allocated resources and notifies
the owner object (mailbox_t) about the fact. Subsequent invocation of
mailbox_get_message results in allocating new object for that message.

Does this sound reasonable?

Regards,
Sergey