To-be-close confusion...

[Paul Ducklin <pducklin@...>]

I think that the 5.4.0 reference manual ought to:

* Add __close and __gc into the list of metamethod events so that all valid metamethods are clearly documented in one place.

* Explain the difference between __close and __gc, and clarify that closing a variable doesn’t finalize it.

(That was not at all clear to me until someone mentioned it here. When you think of “closing” something, the obvious examples are files and sockets, and when you close them you have finished with them and their resources can be reclaimed at once.)

* Give a simple example of how each might be used. (I know it’s a reference manual not a training book but there are useful examples elsewhere in it and they help a lot.)

The biggest problem I have with “toclose” is that having come across it in the manual I still have no real idea why it’s there or what I can do with it that I can’t already do with a finalizer. 

It’s also not that clear how to use it, given that the manual says that to-be-closed variables are constants. My thought is that seems like a great feature for things like files and sockets as a way of recovering cleanly from errors - but I’ve never thought of files and sockets as “constant variables” because they are all about side effects and continuously changing state.

In short: why do I need <toclose>, what do I do with it, and how do I use it properly?