Fused Types (Templates)

Fused types allow you to have one type definition that can refer to multipletypes. This allows you to write a single static-typed cython algorithm that canoperate on values of multiple types. Thus fused types allow genericprogramming and are akin to templates in C++ or generics in languages likeJava / C#.

Note

Fused types are not currently supported as attributes of extensiontypes. Only variables and function/method arguments can be declaredwith fused types.

Quickstart

from __future__ import print_function
 
ctypedef fused char_or_float:
    char
    float
 
 
cpdef char_or_float plus_one(char_or_float var):
    return var + 1
 
 
def show_me():
    cdef:
        char a = 127
        float b = 127
    print('char', plus_one(a))
    print('float', plus_one(b))

This gives:

>>> show_me()
char -128
float 128.0

plus_one(a) “specializes” the fused type char_or_float as a char,whereas plus_one(b) specializes char_or_float as a float.

Declaring Fused Types

Fused types may be declared as follows:

cimport cython
 
ctypedef fused my_fused_type:
    cython.int
    cython.double

This declares a new type called myfused_type which can be _either anint or a double. Alternatively, the declaration may be written as:

my_fused_type = cython.fused_type(cython.int, cython.float)

Only names may be used for the constituent types, but they may be any(non-fused) type, including a typedef. i.e. one may write:

ctypedef double my_double
my_fused_type = cython.fused_type(cython.int, my_double)

Using Fused Types

Fused types can be used to declare parameters of functions or methods:

cdef cfunc(my_fused_type arg):
    return arg + 1

If the you use the same fused type more than once in an argument list, then eachspecialization of the fused type must be the same:

cdef cfunc(my_fused_type arg1, my_fused_type arg2):
    return cython.typeof(arg1) == cython.typeof(arg2)

In this case, the type of both parameters is either an int, or a double(according to the previous examples). However, because these arguments use thesame fused type my_fused_type, both arg1 and arg2 arespecialized to the same type. Therefore this function returns True for everypossible valid invocation. You are allowed to mix fused types however:

def func(A x, B y):
    ...

where A and B are different fused types. This will result inspecialized code paths for all combinations of types contained in Aand B.

Fused types and arrays

Note that specializations of only numeric types may not be very useful, as onecan usually rely on promotion of types. This is not true for arrays, pointersand typed views of memory however. Indeed, one may write:

def myfunc(A[:, :] x):
    ...
 
# and
 
cdef otherfunc(A *x):
    ...

Note that in Cython 0.20.x and earlier, the compiler generated the full crossproduct of all type combinations when a fused type was used by more than onememory view in a type signature, e.g.

def myfunc(A[:] a, A[:] b):
    # a and b had independent item types in Cython 0.20.x and earlier.
    ...

This was unexpected for most users, unlikely to be desired, and also inconsistentwith other structured type declarations like C arrays of fused types, which wereconsidered the same type. It was thus changed in Cython 0.21 to use the sametype for all memory views of a fused type. In order to get the originalbehaviour, it suffices to declare the same fused type under different names, andthen use these in the declarations:

ctypedef fused A:
    int
    long
 
ctypedef fused B:
    int
    long
 
def myfunc(A[:] a, B[:] b):
    # a and b are independent types here and may have different item types
    ...

To get only identical types also in older Cython versions (pre-0.21), a ctypedefcan be used:

ctypedef A[:] A_1d
 
def myfunc(A_1d a, A_1d b):
    # a and b have identical item types here, also in older Cython versions
    ...

Selecting Specializations

You can select a specialization (an instance of the function with specific orspecialized (i.e., non-fused) argument types) in two ways: either by indexing orby calling.

Indexing

You can index functions with types to get certain specializations, i.e.:

cfunc[cython.p_double](p1, p2)
 
# From Cython space
func[float, double](myfloat, mydouble)
 
# From Python space
func[cython.float, cython.double](myfloat, mydouble)

If a fused type is used as a base type, this will mean that the base type is thefused type, so the base type is what needs to be specialized:

cdef myfunc(A *x):
    ...
 
# Specialize using int, not int *
myfunc[int](myint)

Calling

A fused function can also be called with arguments, where the dispatch isfigured out automatically:

cfunc(p1, p2)
func(myfloat, mydouble)

For a cdef or cpdef function called from Cython this means that thespecialization is figured out at compile time. For def functions thearguments are typechecked at runtime, and a best-effort approach is performed tofigure out which specialization is needed. This means that this may result in aruntime TypeError if no specialization was found. A cpdef function istreated the same way as a def function if the type of the function isunknown (e.g. if it is external and there is no cimport for it).

The automatic dispatching rules are typically as follows, in order ofpreference:

• try to find an exact match
• choose the biggest corresponding numerical type (biggest float, biggestcomplex, biggest int)

Built-in Fused Types

There are some built-in fused types available for convenience, these are:

cython.integral # short, int, long
cython.floating # float, double
cython.numeric  # short, int, long, float, double, float complex, double complex

Casting Fused Functions

Fused cdef and cpdef functions may be cast or assigned to C function pointers as follows:

cdef myfunc(cython.floating, cython.integral):
    ...
 
# assign directly
cdef object (*funcp)(float, int)
funcp = myfunc
funcp(f, i)
 
# alternatively, cast it
(<object (*)(float, int)> myfunc)(f, i)
 
# This is also valid
funcp = myfunc[float, int]
funcp(f, i)

Type Checking Specializations

Decisions can be made based on the specializations of the fused parameters.False conditions are pruned to avoid invalid code. One may check with is,is not and == and != to see if a fused type is equal to a certainother non-fused type (to check the specialization), or use in and not into figure out whether a specialization is part of another set of types(specified as a fused type). In example:

ctypedef fused bunch_of_types:
    ...
 
ctypedef fused string_t:
    cython.p_char
    bytes
    unicode
 
cdef cython.integral myfunc(cython.integral i, bunch_of_types s):
    cdef int *int_pointer
    cdef long *long_pointer
 
    # Only one of these branches will be compiled for each specialization!
    if cython.integral is int:
        int_pointer = &i
    else:
        long_pointer = &i
 
    if bunch_of_types in string_t:
        print("s is a string!")

Conditional GIL Acquiring / Releasing

Acquiring and releasing the GIL can be controlled by a conditionwhich is known at compile time (see Conditional Acquiring / Releasing the GIL).

This is most useful when combined with fused types.A fused type function may have to handle both cython native types(e.g. cython.int or cython.double) and python types (e.g. object or bytes).Conditional Acquiring / Releasing the GIL provides a method for runningthe same piece of code either with the GIL released (for cython native types)and with the GIL held (for python types).:

cimport cython
 
ctypedef fused double_or_object:
    cython.double
    object
 
def increment(double_or_object x):
    with nogil(double_or_object is cython.double):
        # Same code handles both cython.double (GIL is released)
        # and python object (GIL is not released).
        x = x + 1
    return x

signatures

Finally, function objects from def or cpdef functions have an attributesignatures, which maps the signature strings to the actual specializedfunctions. This may be useful for inspection. Listed signature strings may alsobe used as indices to the fused function, but the index format may change betweenCython versions:

specialized_function = fused_function["MyExtensionClass|int|float"]

It would usually be preferred to index like this, however:

specialized_function = fused_function[MyExtensionClass, int, float]

Although the latter will select the biggest types for int and float fromPython space, as they are not type identifiers but builtin types there. Passingcython.int and cython.float would resolve that, however.

For memoryview indexing from python space we can do the following:

ctypedef fused my_fused_type:
    int[:, ::1]
    float[:, ::1]
 
def func(my_fused_type array):
    ...
 
my_fused_type[cython.int[:, ::1]](myarray)

The same goes for when using e.g. cython.numeric[:, :].