Improve memory management documentation

[dimaqq]

Looking at old SO discussion (e.g. https://stackoverflow.com/a/6610/705086 ) it looks like when SomeOBJCClass.alloc().init() is called from Python code, it becomes Python's responsibility either to .release() the resulting object on the spot, or to mark it for GC at the bottom of event loop using .autorelease().

Is that correct?

If that's correct, it must be documented...

[dimaqq]

Actually reading up on ARC, I'm completely confused... are calls to .alloc() recorded to current autorelease pool by the compiler or runtime?

Depending on that, Python must or must not call .[auto]release()...

[dgelessus]

ARC is a compiler feature, it makes the compiler insert retain/release calls so the programmer doesn't have to. Because rubicon-objc operates at the runtime level, there is no way to use ARC. That means you have to insert retain/release/autorelease calls in the correct places, like you would without ARC.

Alternatively, it would be possible to make rubicon-objc call retain and release automatically. This is how Pythonista's objc_util module does it - it calls retain when an ObjCInstance is created, and release when it is garbage-collected (in __del__). The only issue with this is that it needs special cases for alloc/copy/mutableCopy/new methods, which return an already retained object (docs).

[mhsmith]

it would be possible to make rubicon-objc call retain and release automatically. This is how Pythonista's objc_util module does it - it calls retain when an ObjCInstance is created, and release when it is garbage-collected (in __del__

This was implemented in #201, but the documentation is still lacking:

• rubicon-objc-api says "Rubicon currently does not perform any automatic memory management on the Objective-C object wrapped in an ObjCInstance", which is no longer true.
• memory-management says "You won’t have to manage reference counts in Python, Rubicon Objective-C will do that work for you." This is over-optimistic, as is shown by the various manual retain/release calls in Toga, and the discussion in Improve correspondence between ObjectiveC objects and Python wrappers #256.
• The fact that calling release or autorelease disables the automatic release in __del__ is mentioned in those methods' docstrings, but those strings aren't included in the HTML documentation.