I'm considering making parts of my C bindings controlled types because the underlying library uses reference-counted "handles" to denote objects. For example, a source is a handle, just as a buffer containing audio data is a handle (at least in the public interface).

The Ada Style Guide on OOP as well as SEC. 7.6 of the ARM are (at least to me) quite confusing on how controlled types work. If I do make handles controlled types, I need the following to happen, exactly as specified:

• When someone causes a handle to be cloned or copied, its reference count must be incremented only once.
• When a handle moves out of scope, its reference count must only be decremented once.

Secondarily, handles should be store-able (say, in Vectors or Lists), and in such a case, their reference count must be incremented only once. These are critical invariants; a handle is only "destroyed" in the underlying library when its reference count reaches zero, and if more than one increment of the reference count occurs, it could cause memory leaks or other undesirable behavior (e.g. sounds playing longer than expected).

The relevant section of the ARM makes the entire process of assignment and finalization seem overly complicated and difficult to understand. In particular, it raises the following questions in my mind:

1. When an objects Adjust procedure is called, is it only called once, or is it called multiple times?
2. The ARM makes it sound like Finalize is called multiple times, once for the "anonymous object" and once when the scope (lifetime?) of the object ends. Is this the case, or is the procedure only called when the objects scope ends?
3. If a controlled object is stored in a container or other type (that may or may not be a controlled type of its own), is the Adjust/Initialize/Finalize procedure called on that stored object? If so, when?

For now my public APIs have a Clone and Drop procedure for incrementing and decrementing the reference counts of handles, but I would like to do away with this interface (as users could trivially forget to call these procedures, and I'm designing it in an object-oriented way), but before I switch over to controlled types I'd like to ensure that the reference count invariants hold at all times and that increments and decrements of handles are not done at unexpected points of execution by the runtime. Not to mention I'd like to ensure I fully understand controlled types.