Libuv: Docs suggestion: When to `free()` handle data

[leonerd]

I'd like to suggest an improvement for the documentation.

I couldn't find anywhere mention of exactly when you ought to free() the per-handle allocation that was previously malloc()'ed. A lot of the simple examples use static allocation so they don't matter, but many of the larger cases involving malloc don't mention it. I have found by experimentation and comparing to other implementations, that this is what the closed_cb of uv_close() is for. It would be nice to explicitly mention that somewhere in the docs, to guide new developers on how to avoid that class of memory leak.

If this is wanted, I can have a go at writing something and send a patch.

[bnoordhuis]

Sounds like a good idea to me. Pull request welcome!

[leonerd]

Alrighty. What sorts of guarantees can I claim in the docs then? In particular I'd like to state the following facts:

• libuv may still be using memory allocated to a handle after uv_close(), so it is not yet safe to free() such memory immediately after calling uv_close().
• libuv will no longer use any of the handle allocation memory after it has invoked the closed_cb callback given to uv_close(), so that code is permitted to free() or otherwise reclaim such allocation if it requires.

[saghul]

👍

[vcunat]

The current docs on uv_close() suggests to do free() in the callback. Perhaps I'm missing your point?

[bnoordhuis]

I think @vcunat is right. I'll close this out then.

[leonerd]

The only text I can find is

It gives you a chance to free up any resources associated with the handle.

I'd like some wording that specifically says "you can reclaim all of the memory used by the handle and we promise we won't touch it and risk a segfault by now", or something around that. The current wording doesn't really feel strong enough.

[bnoordhuis]

It also says this: _Moreover, the memory can only be released in close_cb or after it has returned._

Can you open a PR if you think it should be reworded?

[leonerd]

Some more words there would be good. I think also an example program, because all of the examples use statically-allocated handles so there's nothing to cargo-cult it from even. Even if just a couple of the examples did a fairly pointless malloc() + free() cycle, it would show the point far easier than more wording in the docs.

[bnoordhuis]

When you say "the examples" you mean the guide? The reference documentation is intentionally light on example code but the guide has several examples that show how and when to allocate and release, e.g., the cgi and dns examples.

[leonerd]

Any of the examples in the beginning of http://docs.libuv.org/en/v1.x/guide.html

The DNS example http://docs.libuv.org/en/v1.x/guide/networking.html#querying-dns talks about uv_freeaddrinfo(), but no just malloc/free'ing of a handle.

I don't see what might be a CGI example in there.

[leonerd]

E.g. lets take the simple TCP one. All I'd like is an example that instead of

int main() {
    loop = uv_default_loop();

    uv_tcp_t server;
    uv_tcp_init(loop, &server);

starts off

int main() {
    loop = uv_default_loop();

    uv_tcp_t *server = malloc(sizeof(uv_tcp_t));
    uv_tcp_init(loop, server);

and then showed somewhere where the matching free() call for that goes.