Merge pull request #4947 from stuartarchibald/doc/jitclass_dict

Document jitclass with numba.typed use.

docs/source/user/jitclass.rst

@@ -61,6 +61,86 @@ initializing each defined fields.  Uninitialized fields contains garbage data.
 Methods and properties (getters and setters only) can be defined.  They will be
 automatically compiled.
 
+Specifying ``numba.typed`` containers as class members
+======================================================
+It is often desirable to use a ``numba.typed.Dict`` or a ``numba.typed.List`` as
+a class member in a ``jitclass``. Methods for using these types and various
+common patterns are presented in the following:
+
+First, using explicit Numba types and explicit construction.
+
+.. code-block:: python
+
+    from numba import jitclass, types, typed
+
+    # key and value types
+    kv_ty = (types.int64, types.unicode_type)
+
+    # A container class with:
+    # * member 'd' holding a typed dictionary of int64 -> unicode string (kv_ty)
+    # * member 'l' holding a typed list of float64
+    @jitclass([('d', types.DictType(*kv_ty)),
+               ('l', types.ListType(types.float64))])
+    class ContainerHolder(object):
+        def __init__(self):
+            # initialize the containers
+            self.d = typed.Dict.empty(*kv_ty)
+            self.l = typed.List.empty_list(types.float64)
+
+    container = ContainerHolder()
+    container.d[1] = "apple"
+    container.d[2] = "orange"
+    container.l.append(123.)
+    container.l.append(456.)
+    print(container.d) # {1: apple, 2: orange}
+    print(container.l) # [123.0, 456.0]
+
+Another useful pattern is to use the ``numba.typed`` container attribute
+``_numba_type_`` to find the type of a container, this can be accessed directly
+from an instance of the container in the Python interpreter. The same
+information can be obtained by calling :func:`numba.typeof` on the instance. For
+example:
+
+.. code-block:: python
+
+    from numba import jitclass, typed, typeof
+
+    d = typed.Dict()
+    d[1] = "apple"
+    d[2] = "orange"
+    l = typed.List()
+    l.append(123.)
+    l.append(456.)
+
+
+    @jitclass([('d', typeof(d)), ('l', typeof(l))])
+    class ContainerInstHolder(object):
+        def __init__(self, dict_inst, list_inst):
+            self.d = dict_inst
+            self.l = list_inst
+
+    container = ContainerInstHolder(d, l)
+    print(container.d) # {1: apple, 2: orange}
+    print(container.l) # [123.0, 456.0]
+
+It is worth noting that the instance of the container in a ``jitclass`` must be
+initialized before use, for example, this will cause an invalid memory access
+as ``self.d`` is written to without ``d`` being initialized as a ``type.Dict``
+instance of the type specified.
+
+.. code-block:: python
+
+    from numba import jitclass, types
+
+    dict_ty = types.DictType(types.int64, types.unicode_type)
+
+    @jitclass([('d', dict_ty)])
+    class NotInitilisingContainer(object):
+        def __init__(self):
+            self.d[10] = "apple" # this is invalid, `d` is not initialized
+
+    NotInitilisingContainer() # segmentation fault/memory access violation
+
 
 Support operations
 ==================