融合类型（模板）

原文： http://docs.cython.org/en/latest/src/userguide/fusedtypes.html

融合类型允许您有一个可以引用多种类型的类型定义。这允许您编写一个静态类型的 cython 算法，该算法可以对多种类型的值进行操作。因此，融合类型允许泛型编程，类似于 C ++中的模板或 Java / C＃等语言中的泛型。

注意

目前不支持融合类型作为扩展类型的属性。只能使用融合类型声明变量和函数/方法参数。

快速入门

  1. from __future__ import print_function
  3. ctypedef fused char_or_float:
  4.     char
  5.     float
  7. cpdef char_or_float plus_one(char_or_float var):
  8.     return var + 1
  10. def show_me():
  11.     cdef:
  12.         char a = 127
  13.         float b = 127
  14.     print('char', plus_one(a))
  15.     print('float', plus_one(b))

这给出了：

  1. >>> show_me()
  2. char -128
  3. float 128.0

plus_one(a)将“融合型”char_or_float“专门化”为char，而plus_one(b)将char_or_float专门化为float。

声明熔断类型

融合类型可以声明如下：

  1. cimport cython
  3. ctypedef fused my_fused_type:
  4.     cython.int
  5.     cython.double

这声明了一个名为my_fused_type的新类型，它可以是和int 或 a double。或者，声明可以写成：

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

只有名称可用于组成类型，但它们可以是任何（非融合）类型，包括 typedef。即可以写：

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

使用融合类型

融合类型可用于声明函数或方法的参数：

  1. cdef cfunc(my_fused_type arg):
  2.     return arg + 1

如果在参数列表中多次使用相同的融合类型，则融合类型的每个特化必须相同：

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

在这种情况下，两个参数的类型都是 int 或 double（根据前面的示例）。但是，因为这些参数使用相同的融合类型my_fused_type，所以arg1和arg2都专用于相同类型。因此，对于每个可能的有效调用，此函数都返回 True。但是你可以混合融合类型：

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

其中A和B是不同的融合类型。这将为A和B中包含的所有类型组合生成专门的代码路径。

融合类型和数组

请注意，仅数字类型的特化可能不是非常有用，因为通常可以依赖于类型的提升。但是，对于内存的数组，指针和类型化视图，情况并非如此。的确，有人可能写道：

  1. def myfunc(A[:, :] x):
  2.     ...
  4. # and
  6. cdef otherfunc(A *x):
  7.     ...

请注意，在 Cython 0.20.x 及更早版本中，当类型签名中的多个内存视图使用融合类型时，编译器会生成所有类型组合的完整交叉积。

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

这对于大多数用户来说是出乎意料的，不太可能是期望的，并且与其他结构化类型声明（例如融合类型的 C 数组）不一致，这些声明被认为是相同的类型。因此在 Cython 0.21 中进行了更改，以便对融合类型的所有内存视图使用相同的类型。为了获得原始行为，只需在不同的名称下声明相同的融合类型，然后在声明中使用它们：

  1. ctypedef fused A:
  2.     int
  3.     long
  5. ctypedef fused B:
  6.     int
  7.     long
  9. def myfunc(A[:] a, B[:] b):
  10.     # a and b are independent types here and may have different item types
  11.     ...

要在较旧的 Cython 版本（0.21 之前版本）中仅获得相同类型，可以使用ctypedef：

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

选择专业化

您可以通过两种方式选择特化（具有特定或专用（即非融合）参数类型的函数实例）：通过索引或通过调用。

索引

您可以使用类型索引函数以获得某些特化，即：

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

如果使用融合类型作为基类型，这将意味着基类型是融合类型，因此基类型需要专门化：

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

调用

也可以使用参数调用融合函数，其中自动计算调度：

  1. cfunc(p1, p2)
  2. func(myfloat, mydouble)

对于从 Cython 调用的cdef或cpdef函数，这意味着在编译时计算出特化。对于def函数，在运行时对参数进行类型检查，并执行尽力而为的方法来确定需要哪种特化。这意味着如果没有找到特化，这可能会导致运行时TypeError。如果函数的类型未知，则cpdef函数的处理方式与def函数的处理方式相同（例如，如果它是外部的，并且没有 cimport）。

自动调度规则通常如下所示，按优先顺序排列：

  • 试着找到完全匹配
  • 选择最大的相应数值类型（最大浮点数，最大复数，最大 int）

内置熔断类型

为方便起见，有一些内置的融合类型，它们是：

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

铸造熔断函数

融合的cdef和cpdef函数可以转换或分配给 C 函数指针，如下所示：

  1. cdef myfunc(cython.floating, cython.integral):
  2.     ...
  4. # assign directly
  5. cdef object (*funcp)(float, int)
  6. funcp = myfunc
  7. funcp(f, i)
  9. # alternatively, cast it
  10. (<object (*)(float, int)> myfunc)(f, i)
  12. # This is also valid
  13. funcp = myfunc[float, int]
  14. funcp(f, i)

类型检查专业化

可以基于融合参数的特化来做出决定。修剪错误条件以避免无效代码。可以检查is，is not和==和!=以查看融合类型是否等于某个其他非融合类型（检查专业化），或使用in和[COD5 判断专门化是否是另一组类型（指定为融合类型）的一部分。例如：

  1. ctypedef fused bunch_of_types:
  2.     ...
  4. ctypedef fused string_t:
  5.     cython.p_char
  6.     bytes
  7.     unicode
  9. cdef cython.integral myfunc(cython.integral i, bunch_of_types s):
  10.     cdef int *int_pointer
  11.     cdef long *long_pointer
  13.     # Only one of these branches will be compiled for each specialization!
  14.     if cython.integral is int:
  15.         int_pointer = &i
  16.     else:
  17.         long_pointer = &i
  19.     if bunch_of_types in string_t:
  20.         print("s is a string!")

条件 GIL 获取/释放

获取和释放 GIL 可以通过编译时已知的条件来控制（参见 条件获取/释放 GIL）。

当与融合类型结合使用时，这是最有用的。融合类型函数可能必须处理 cython 本机类​​型（例如 cython.int 或 cython.double）和 python 类型（例如对象或字节）。条件获取/释放 GIL 提供了一种运行相同代码的方法，无论是发布 GIL（对于 cython 本机类​​型）还是持有 GIL（对于 python 类型）：

  1. cimport cython
  3. ctypedef fused double_or_object:
  4.     cython.double
  5.     object
  7. def increment(double_or_object x):
  8.     with nogil(double_or_object is cython.double):
  9.         # Same code handles both cython.double (GIL is released)
  10.         # and python object (GIL is not released).
  11.         x = x + 1
  12.     return x

signatures

最后，来自def或cpdef函数的函数对象具有 signatures 属性，该属性将签名字符串映射到实际的专用函数。这可能对检查有用。列出的签名字符串也可以用作融合函数的索引，但索引格式可能会在 Cython 版本之间发生变化：

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

通常最好像这样索引，但是：

  1. specialized_function = fused_function[MyExtensionClass, int, float]

虽然后者将从 Python 空间中选择int和float的最大类型，因为它们不是类型标识符，而是内置类型。但是，通过cython.int和cython.float可以解决这个问题。

对于来自 python 空间的 memoryview 索引，我们可以执行以下操作：

  1. ctypedef fused my_fused_type:
  2.     int[:, ::1]
  3.     float[:, ::1]
  5. def func(my_fused_type array):
  6.     ...
  8. my_fused_type[cython.int[:, ::1]](myarray)

使用例如同样的方法也是如此。 cython.numeric[:, :]。