8.2.2.1. Introduction
Numba does not yet support user-defined classes.
Classes provide useful abstraction and promote modularity when used
right. In the simplest sense, a class specifies the set of data and
operations as attributes and methods, respectively.
A class instance is an instantiation of that class.
This proposal will focus on supporting this simple usecase of classes–with
just attributes and methods. Other features, such as class methods, static
methods, and inheritance are deferred to another proposal, but we believe
these features can be easily implemented given the foundation described here.
8.2.2.2. Proposal: jit-classes
A JIT-classes is more restricted than a Python class.
We will focus on the following operations on a class and its instance:
- Instantiation: create an instance of a class using the class object as the
constructor:
cls(*args, **kwargs)
- Destruction: remove resources allocated during instantiation and release
all references to other objects.
- Attribute access: loading and storing attributes using
instance.attr
syntax.
- Method access: loading methods using
instance.method syntax.
With these operations, a class object (not the instance) does not need to be
materialize. Using the class object as a constructor is fully resolved (a
runtime implementation is picked) during the typing phase in the compiler.
This means a class object will not be first class. On the other hand,
implementating a first-class class object will require an
“interface” type, or the type of class.
The instantiation of a class will allocate resources for storing the data
attributes. This is described in the “Storage model” section. Methods are
never stored in the instance. They are information attached to the class.
Since a class object only exists in the type domain, the methods will also be
fully resolved at the typing phase. Again, numba do not have first-class
function value and each function type maps uniquely to each function
implementation (this needs to be changed to support function value as argument).
A class instance can contain other NRT reference-counted object as attributes.
To properly clean up an instance, a destructor is called when the reference
count of the instance is dropped to zero. This is described in the
“Reference count and descructor” section.
8.2.2.2.1. Storage model
For compatibility with C, attributes are stored in a simple plain-old-data
structure. Each attribute are stored in a user-defined order in a padded
(for proper alignment), contiguous memory region. An instance that contains
three fields of int32, float32, complex64 will be compatible with the following
C structure:
struct {
int32 field0;
float32 field1;
complex64 field2;
};
This will also be comptabile with an aligned numpy structure dtype.
8.2.2.2.2. Methods
Methods are regular function that can be bounded to an instance.
They can be compiled as regular function by numba.
The operation getattr(instance, name) (getting an attribute name from
instance) binds the instance to the requested method at runtime.
The special __init__ method is also handled like regular functions.
__del__ is not supported at this time.
8.2.2.2.3. Reference count and destructor
An instance of jit-class is reference-counted by NRT. Since it may contain
other NRT tracked object, it must call a destructor when its reference count
dropped to zero. The destructor will decrement the reference count of all
attributes by one.
At this time, there is no support for user defined __del__ method.
Proper cleanup for cyclic reference is not handled at this time.
Cycles will cause memory leak.
8.2.2.2.4. Type inference
So far we have not described the type of the attributes or the methods.
Type information is necessary to materailize the instance (e.g. allocate the
storage). The simplest way is to let user provide the type of each attributes
as well as the ordering; for instance:
dct = OrderedDict()
dct['x'] = int32
dct['y'] = float32
Allowing user to supply an ordered dictionary will provide the name, ordering
and types of the attributes. However, this statically typed semantic is not as
flexible as the Python semantic which behaves like a generic class.
Inferring the type of attributes is difficult. In a previous attempt to
implement JIT classes, the __init__ method is specialized to capture
the type stored into the attributes. Since the method can contain arbitrary
logic, the problem can become a dependent typing problem if types are assigned
conditionally depending on the value. (Very few languages implement dependent
typing and those that does are mostly theorem provers.)
8.2.2.2.4.1. Example: typing function using an OrderedDict
spec = OrderedDict()
spec['x'] = numba.int32
spec['y'] = numba.float32
@jitclass(spec)
class Vec(object):
def __init__(self, x, y):
self.x = x
self.y = y
def add(self, dx, dy):
self.x += dx
self.y += dy
8.2.2.2.4.2. Example: typing function using a list of 2-tuples
spec = [('x', numba.int32),
('y', numba.float32)]
@jitclass(spec)
class Vec(object):
...
8.2.2.2.4.3. Creating multiple jitclasses from a single class object
The jitclass(spec) decorator creates a new jitclass type even when applied to
the same class object and the same type specification.
class Vec(object):
...
Vec1 = jitclass(spec)(Vec)
Vec2 = jitclass(spec)(Vec)
# Vec1 and Vec2 are two different jitclass types
8.2.2.2.5. Usage from the Interpreter
When constructing a new instance of a jitclass, a “box” is created that wraps
the underlying jitclass instance from numba. Attributes and methods are
accessible from the interpreter. The actual implementation will be in numba
compiled code. Any Python object is converted to its native
representation for consumption in numba. Similarly, the returned value is
converted to its Python representation. As a result, there may be overhead in
manipulating jitclass instances in the interpreter. This overhead is minimal
and should be easily amortized by more efficient computation in the compiled
methods.
8.2.2.2.6. Support for property, staticmethod and classmethod
The use of property is accepted for getter and setter only. Deleter is not
supported.
The use of staticmethod is not supported.
The use of classmethod is not supported.
8.2.2.2.7. Inheritance
Class inhertance is not considered in this proposal. The only accepted base
class for a jitclass is object.
8.2.2.2.8. Supported targets
Only the CPU target (including the parallel target) is supported.
GPUs (e.g. CUDA and HSA) targets are supported via an immutable version of the
jitclass instance, which will be described in a separate NBEP.
8.2.2.2.9. Other properties
Given:
spec = [('x', numba.int32),
('y', numba.float32)]
@jitclass(spec)
class Vec(object):
...
isinstance(Vec(1, 2), Vec) is True.type(Vec(1, 2)) may not be Vec.
8.2.2.2.10. Future enhancements
This proposal has only described the basic semantic and functionality of a
jitclass. Additional features will be described in future enhancement
proposals.
Numba
0.48