Add note about module destructors

[virtuald]

• Technique provided by @jagerman
• FixesDocumentation: module destructor #638

[wjakob]

This looks good. Quick question: can't the unused value simply be nullptr?

[jagerman]

If I recall correctly, Python won't allow a nullptr for it. Of course, if you have some meaningful value, you should use it instead.

[dean0x7d]

Would Py_None work?

[virtuald]

Looking at the API docs for capsule:

• The pointer argument may not be NULL
• It's a void*, so it can be anything you want it to be

Unless someone tries to get the pointer, I don't believe the API will ever try to dereference it, so in theory you could do Py_None if you wanted.

[jagerman]

Instead of a static local variable, how about amending the example to:

// the capsule needs a non-null pointer to reference; if you don't have anything better, create a simple one:int *data = newint(123);
py::capsule cleanup(data, [](PyObject * capsule) {
int *data = PyCapsule_GetPointer(capsule, nullptr);
// do cleanup here -- this function is called with the GIL helddelete data;
});

which also suggests an obvious way of how to pass data into the capsule.

You should also add a note that py::capsule requires either a lambda without capture (as in the example), or a regular function reference, and must not return a value (i.e. must be void).

[wjakob]

I was surprised at how inelegant our way of dealing with py::capsule destructors is ;)

I submitted a separate PR to deal with this before we document the API and then can't change it anymore #752.

[wjakob]

Can you update the PR to take the future changes into account?

Thanks!

[wjakob]

closing in favor of #752