
Documentation of memory management in Carob
-------------------------------------------


There is a strict hierarchy among the three main types:

Connection
  |
  |_____ Statement
  |         .
  |         .
  |         .
   \____ Statement
               |
               |________ ResultSet
               |         .
               |         .
               |         .
               |
                \_______ ResultSet


Ownership
---------

Lines show ownership, so:
- a Connection owns a number of Statements;
- each Statement is owned by one and only one Connection;
- same thing below for Statements and ResultSets

Property means that:
- the only way to create   lower objects is to ask the upper object to do it.
- the only way to delete a lower object  is to ask the upper object to do it.

Connection is owned by the user.

Deletion is obviously recursive.


The .close() method
-------------------

So far, the only way allowed to free resources allowed is to delete
the connection [1]; this is too restrictive. So the .close() method
provides partial clean-ups on any object. It *deletes* all lower
objects owned, frees any remote (database) resources held and frees
now obsolete local fields as a memory optimisation.

Some closed objects can be re-initialized and used again.




Footnote
--------

[1] actually some actions may delete objects as a side-effect. For
instance:
- executing a new query with an existing Statement will delete all
  ResultSets of the previous query ("copy-assignement" semantic);
- Statement.getMoreResults(some_close_flag) may delete the previous
  ResultSet of the current query.
- others?

But this is indirect; sometimes the user may want to "just free
resources".
