Commits

Ronald Oussoren  committed ac12b57

Add some notes on autorelease pools

  • Participants
  • Parent commits 9cb8148

Comments (0)

Files changed (1)

File pyobjc-core/Doc/intro.rst

 Preface
 -------
 
-PyObjC is a bridge between Python and Objective-C.  It allows Python 
+PyObjC is a bridge between Python and Objective-C.  It allows Python
 scripts to use and extend existing Objective-C class libraries;
 most importantly the `Cocoa libraries`_ by `Apple`_.
 
 This document describes how to use Objective-C class libraries from Python
-scripts and how to interpret the documentation of those libraries from the 
+scripts and how to interpret the documentation of those libraries from the
 point of view of a Python programmer.
 
 .. _`Apple`: http://www.apple.com/
       # note the trailing underscore
       someObject.setValue_(aValue)
 
-There are a few additional rules regarding message dispatch, see the 
+There are a few additional rules regarding message dispatch, see the
 `Overview of the bridge`_ for the complete rundown.
 
 Two-phase instantiation
 
 An important difference between Python and Objective-C is that the latter is
 not a pure object-oriented language.  Some values are not objects, but values
-of plain C types, such as ``int`` and ``double``.  These basic C types can 
-be used as the types of arguments and the return value of methods. 
+of plain C types, such as ``int`` and ``double``.  These basic C types can
+be used as the types of arguments and the return value of methods.
 
-Object allocation and initialization are explicit and separate actions in 
+Object allocation and initialization are explicit and separate actions in
 Objective-C.  The former is done by the class-method ``alloc``, while the
 latter is done by instance methods whose name customarily starts with ``init``.
 
  .. sourcecode:: objective-c
 
     [anArray indexOfObject:someObject inRange:someRange]
-    
+
 Target:
     ``anArray``
 
 Selector:
     ``indexOfObject:inRange:``
-    
+
 Arguments:
     ``someObject``, ``someRange``
 
  .. sourcecode:: python
 
     anArray.indexOfObject_inRange_(someObject, someRange)
-    
+
 This may be awkward and "unpythonic" at first, however this syntax is necessary
 to preserve the semantics of Objective-C message dispatch.
 
         //     return self
         return self;
     }
-        
+
 
     // an accessor, instance variables (attributes) are in a separate
     // namespace and are considered "private"
 Objective-C also features exceptions, but they are typically only used for
 disaster recovery, not error handling, so you will not encounter them very
 often.  Read `The Objective-C Programming Language`_ if you want to
-know more about exceptions in Objective-C. 
+know more about exceptions in Objective-C.
 
 One thing to keep in mind when translating Objective-C snippets to Python is
 that any message can be sent to ``nil``, and the return value of that message
 Classes
 .......
 
-Objective-C classes are visible as (new-style) Python classes and can be 
+Objective-C classes are visible as (new-style) Python classes and can be
 subclassed just like normal Python classes.  All the usual introspection
-mechanisms work as well, as do ``__slots__`` and descriptors.  The major 
-differences between normal Python classes and Objective-C classes are the way 
+mechanisms work as well, as do ``__slots__`` and descriptors.  The major
+differences between normal Python classes and Objective-C classes are the way
 that instances are created and initialized, and the fact that Objective-C
 selectors look strange when translated to Python methods.
 
 prefix made much more sense when it was called NeXTstep, but persists to this
 day for compatibility reasons.
 
-As described in `Objective-C for PyObjC users`_ the creation of Objective-C 
+As described in `Objective-C for PyObjC users`_ the creation of Objective-C
 objects is a two-stage process.  To initialize objects, first call a
 class method to allocate the memory (typically ``alloc``), and then call an
 initializer (typically starts with ``init``).  Some classes have class methods
 simple translations must take place.  The rules for these translations are:
 
 1. Replace all colons in the selector with underscores:
-  
+
     - ``someMethod:withFoo:andBar:`` translates to ``someMethod_withFoo_andBar_``
 
 2. If the result ``class`` or ``raise`` (Python keywords), append two underscores:
-  
+
     - ``class`` translates to ``class__``
     - ``raise`` translates to ``raise__``
 
     Used to pass data by reference to the function.  This is not a special
     case from Python.
 
-    Instead of a regular value you may also pass in the value ``objc.NULL``, 
+    Instead of a regular value you may also pass in the value ``objc.NULL``,
     when you do that the Objective-C method will receive a NULL pointer instead
     of a pointer to your value.
 
 
     Pass in either ``None`` or ``objc.NULL`` for output arguments.
     to the method. If the value is ``objc.NULL`` the Objective-C code will
-    receive a NULL pointer for this argument, otherwise it will receive a 
-    valid pointer. 
+    receive a NULL pointer for this argument, otherwise it will receive a
+    valid pointer.
 
 ``inout``:
     A combination of in and out (a value is passed by reference, and mutated
     and thus do not have an effect on the number of arguments a method expects.
     See below for notes on how ``inout`` arguments change the return value.
 
-    Instead of a regular value you may also pass in the value ``objc.NULL``, 
+    Instead of a regular value you may also pass in the value ``objc.NULL``,
     when you do that the Objective-C method will receive a NULL pointer instead
     of a pointer to your value.
 
 
 More than one element:
     The return value of this call will be a tuple in the same order as the list.
-    
+
 The rules for pass by reference arguments may look quite complicated, but
 it turns out this is very straightforward when working with them.
 
 type signatures for each method to the Objective-C runtime.  The default
 type signature is for all arguments as well as the return value to be objects (just
 like with normal Python methods).  If there is no return statement in the implementation,
-then the return value will be void.  The bridge will automatically pick a better 
-signature when it has more information available.  Specifically, a method overrides 
+then the return value will be void.  The bridge will automatically pick a better
+signature when it has more information available.  Specifically, a method overrides
 an existing method, the bridge will assume you want to use the same
 method signature.  Furthermore, if the method is implemented in an (informal)
 protocol known to the bridge it will use the signature from the corresponding
 Reference counting
 ..................
 
-The Cocoa libraries, and most (if not all) other class libraries for 
+The Cocoa libraries, and most (if not all) other class libraries for
 Objective-C use explicit reference counting to manage memory.  The methods
-``retain``, ``release`` and ``autorelease`` are used to manage these 
+``retain``, ``release`` and ``autorelease`` are used to manage these
 reference counts.  You won't have to manage reference counts in Python, the
-bridge does all that work for you (but see :doc:`Notes on supported APIs and classes 
+bridge does all that work for you (but see :doc:`Notes on supported APIs and classes
 on Mac OS X </apinotes>` for some advanced issues).
 
 The only reasons reference counts are mentioned at all are to tell you about
-ignoring them, and more importantly to introduce you to some issues w.r.t. 
+ignoring them, and more importantly to introduce you to some issues w.r.t.
 reference counting.
 
-It turns out that Cocoa uses a primitive form of :mod:`weak references <weakref>`.  Those 
-are not true :mod:`weak references <weakref>` as in Python, but use-cases where an object 
+It turns out that Cocoa uses a primitive form of :mod:`weak references <weakref>`.  Those
+are not true :mod:`weak references <weakref>` as in Python, but use-cases where an object
 stores a reference to another object without increasing the reference count
 for that other object.  The bridge cannot solve the issues this introduces
 for you, which means that you get hard crashes when you're not careful when
 actually an autoreleased object that will be cleaned up unless the Objective-C
 code increases its reference count.
 
-The document :doc:`Notes on supported APIs and classes on Mac OS X </apinotes>` contains 
+The document :doc:`Notes on supported APIs and classes on Mac OS X </apinotes>` contains
 information about classes that work with weak references.  The most important
 are notification centers and ``NSOutlineView``, to be exact: the outline view
-stores weak references to the objects return by the method 
+stores weak references to the objects return by the method
 ``outlineView:child:ofItem:`` of its data source.  The easiest way to avoid
 crashes with outline views is to make sure that you model for the view uses
 subclasses of ``NSObject`` to represent the nodes in the outline view.
 objects are the maintainers of wrappers around Objective-C frameworks: they
 have to keep these protocol wrappers up-to-date.
 
-PyObjC will automatically use the information in the ``informal_protocol`` 
+PyObjC will automatically use the information in the ``informal_protocol``
 objects to add the right method signatures to methods, and to warn about
 classes that partially implement a protocol.
 
 `Key-Value Coding`_.  In order to create accessors compatible with this, you
 must use ``objc.accessor`` to create an appropriate selector descriptor.
 
-PyObjC automaticly emits the right `Key-Value Observing`_ notifications when 
+PyObjC automaticly emits the right `Key-Value Observing`_ notifications when
 you set attributes on an Objective-C class. This is however not supported for
-pure python objects. You should therefore use ``NSMutableArray`` instances 
+pure python objects. You should therefore use ``NSMutableArray`` instances
 instead of Python lists for instance variables that will be observed and contain
 a sequence of values (and simularly for ``NSMutableDictionary`` instead of
 ``dict``).
 .. _`Key-Value Observing`: https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/KeyValueObserving/KeyValueObserving.html
 
 NOTE: Key-Value Observing is not supported for "pure" python objects, that
-is instances of classes that don't inherit from ``NSObject``. Adding such 
+is instances of classes that don't inherit from ``NSObject``. Adding such
 support is not possible adding a KVO-like interface to the Python interpreter.
 
 Categories
 
 	objc.classAddMethods(NSObject, [objectFootprint])
 
-This is not very clear, PyObjC therefore also provides the following 
+This is not very clear, PyObjC therefore also provides the following
 mechanism, implemented on top of ``objc.classAddMethods``:
 
  .. sourcecode:: python
 
 Cocoa frameworks are mapped onto Python packages with the same name; that is
 the classes, constants and functions from the AppKit framework are available
-after you import ``AppKit`` in your Python script. 
+after you import ``AppKit`` in your Python script.
 
-These helper modules contain *only* functions, constants and classes that 
-wrap items in the corresponding framework.  All utility functions and classes 
+These helper modules contain *only* functions, constants and classes that
+wrap items in the corresponding framework.  All utility functions and classes
 are located in the ``PyObjCTools`` package and ``objc`` module.  Note that it
 is possible to use ``pydoc`` (or the ``help()``) function with the framework
 wrappers, but that this is not very useful for the entire module due to the
 size of these modules.
 
-This makes it easier to find documentation for an item: if you import it 
+This makes it easier to find documentation for an item: if you import it
 from the wrapper module for an Objective-C framework the documentation for
 that item can be found in the documentation for the framework; otherwise the
 item is documented in the PyObjC documentation.
 
-The module ``PyObjCTools.NibClassBuilder`` can be used to make working with 
-NIB files more convenient.  This module can be used to extract information 
-about classes from NIB files, both as a standalone tool generating source code 
+The module ``PyObjCTools.NibClassBuilder`` can be used to make working with
+NIB files more convenient.  This module can be used to extract information
+about classes from NIB files, both as a standalone tool generating source code
 and during runtime.  See the online documentation for this module for more
 information.
 
 will be create a new ``NSAutoreleasePool`` at the beginning of each run loop iteration
 and release it at the end.
 
+.. warning::
+
+   Autorelease pools are thread global state and will not be shared amongst threads,
+   every thread needs to create its own pool(s).
+
+.. warning::
+
+   It is possible to create nested pools (that is, create a new pool when there already
+   is an active pool), but nested pools must be released in reverse order. The pools
+   form a stack that must be cleaned up by popping pools from the top. When you don't
+   do this you can end up with unexpected behavior, including hard crashes.
+
 Finalizers
 ..........
 
 objects (including subclasses from Python) are already subject to these
 restrictions.  When subclassing an Objective-C class, you may implement
 ``dealloc`` or ``__del__``.  If you implement ``dealloc``, ensure that
-you call the super ``dealloc`` at the end.  If you implement both 
+you call the super ``dealloc`` at the end.  If you implement both
 ``__del__`` and ``dealloc``, the order in which they are called is
 undefined.
 
 
 It is possible for a Python subclass of an Objective-C class to implement
 the ``NSCopying`` protocol.  Some care must be taken when the superclass
-already implements the protocol. 
+already implements the protocol.
 
 Some ``NSCopying`` compliant Objective-C classes copy the template object
 manually.  In those cases the Python subclass must also copy the additional
         app = ["iClass.py"],
         data_files = ["English.lproj"],
     )
-	
+
 During development you typically invoke it from the command line like this:
 
  .. sourcecode:: sh
 
 
 
-.. 
+..
         This section is disabled for now because the Xcode templates aren't maintained.
 
         "IDE approach" : Xcode
         ......................
 
-        PyObjC includes a number of Xcode templates that can be used to 
+        PyObjC includes a number of Xcode templates that can be used to
         develop applications, using the same underlying functionality that
         is in py2app.  These templates are used like any other Xcode template,
         but there are some organizational rules about the template.