6.3。示例：間隔類型 · Numba 0.44 中文文檔

# 6.3。示例：間隔類型 > 原文： [http://numba.pydata.org/numba-doc/latest/extending/interval-example.html](http://numba.pydata.org/numba-doc/latest/extending/interval-example.html) 我們將擴展 Numba 前端以支持它目前不支持的類，以便允許： * 將類的實例傳遞給 Numba 函數 * 在 Numba 函數中訪問類的屬性 * 從 Numba 函數構造并返回類的新實例（以上所有 [nopython 模式](../glossary.html#term-nopython-mode)）我們將混合來自[高級擴展 API](high-level.html#high-level-extending) 和[低級擴展 API](low-level.html#low-level-extending) 的 API，具體取決于給定任務的可用內容。我們的示例的起點是以下純 Python 類： ```py class Interval(object): """ A half-open interval on the real number line. """ def __init__(self, lo, hi): self.lo = lo self.hi = hi def __repr__(self): return 'Interval(%f, %f)' % (self.lo, self.hi) @property def width(self): return self.hi - self.lo ``` ## 6.3.1。擴展打字層 ### 6.3.1.1。創建一個新的 Numba 類型由于 Numba 不知道`Interval`類，我們必須創建一個新的 Numba 類型來表示它的實例。 Numba 不直接處理 Python 類型：它有自己的類型系統，允許不同級別的粒度以及常規 Python 類型不具備的各種元信息。我們首先創建一個類型類`IntervalType`，因為我們不需要參數類型，所以我們實例化一個類型實例`interval_type`： ```py from numba import types class IntervalType(types.Type): def __init__(self): super(IntervalType, self).__init__(name='Interval') interval_type = IntervalType() ``` ### 6.3.1.2。 Python 值的類型推斷就其本身而言，創建一個 Numba 類型并沒有做任何事情。我們必須教 Numba 如何推斷一些 Python 值作為該類型的實例。在這個例子中，它是微不足道的：`Interval`類的任何實例都應被視為屬于`interval_type`類型： ```py from numba.extending import typeof_impl @typeof_impl.register(Interval) def typeof_index(val, c): return interval_type ``` 因此，只要它們是`Interval`的實例，函數參數和全局值就會被認為屬于`interval_type`。 ### 6.3.1.3。操作類型推斷我們希望能夠從 Numba 函數構造區間對象，因此我們必須教 Numba 識別雙參數`Interval(lo, hi)`構造函數。參數應該是浮點數： ```py from numba.extending import type_callable @type_callable(Interval) def type_interval(context): def typer(lo, hi): if isinstance(lo, types.Float) and isinstance(hi, types.Float): return interval_type return typer ``` [`type_callable()`](low-level.html#type_callable "type_callable") 裝飾器指定在為給定的可調用對象（此處為`Interval`類本身）運行類型推斷時應調用修飾函數。修飾函數必須簡單地返回一個將使用參數類型調用的 typer 函數。這個看似錯綜復雜的設置的原因是，typer 函數使 _ 與 _ 完全相同的簽名與打字的 callable 相同。這允許正確處理關鍵字參數。由裝飾函數接收的 _ 上下文 _ 參數在更復雜的情況下非常有用，在這種情況下，計算可調用的返回類型需要解析其他類型。 ## 6.3.2。延伸降低層我們已經完成了關于我們的類型推理添加的 Numba 教學。我們現在必須教 Numba 如何為新操作實際生成代碼和數據。 ### 6.3.2.1。定義原生間隔的數據模型作為一般規則， [nopython 模式](../glossary.html#term-nopython-mode)不適用于 Python 對象，因為它們是由 CPython 解釋器生成的。解釋器使用的表示對于快速本機代碼而言效率太低。因此， [nopython 模式](../glossary.html#term-nopython-mode)中支持的每種類型都必須定義定制的本機表示，也稱為 _ 數據模型 _。數據模型的一個常見情況是不可變的類似結構的數據模型，類似于 C `struct`。我們的 interval 數據類型很方便地屬于該類別，這里有一個可能的數據模型： ```py from numba.extending import models, register_model @register_model(IntervalType) class IntervalModel(models.StructModel): def __init__(self, dmm, fe_type): members = [ ('lo', types.float64), ('hi', types.float64), ] models.StructModel.__init__(self, dmm, fe_type, members) ``` 這指示 Numba 將`IntervalType`類型的值（或其任何實例）表示為兩個字段`lo`和`hi`的結構，每個字段都是雙精度浮點數（`types.float64`）。注意可變類型需要更復雜的數據模型才能在修改后保留其值。它們通常不能存儲和傳遞到堆棧或寄存器，如不可變類型。 ### 6.3.2.2。公開數據模型屬性我們希望數據模型屬性`lo`和`hi`以相同的名稱公開，以便在 Numba 函數中使用。 Numba 提供了一個方便的功能來做到這一點： ```py from numba.extending import make_attribute_wrapper make_attribute_wrapper(IntervalType, 'lo', 'lo') make_attribute_wrapper(IntervalType, 'hi', 'hi') ``` 這將以只讀模式公開屬性。如上所述，可寫屬性不適合此模型。 ### 6.3.2.3。公開財產由于`width`屬性是計算而不是存儲在結構中，我們不能像我們對`lo`和`hi`那樣簡單地公開它。我們必須明確地重新實現它： ```py from numba.extending import overload_attribute @overload_attribute(IntervalType, "width") def get_width(interval): def getter(interval): return interval.hi - interval.lo return getter ``` 您可能會問為什么我們不需要為此屬性公開類型推斷鉤子？答案是`@overload_attribute`是高級 API 的一部分：它在單個 API 中結合了類型推斷和代碼生成。 ### 6.3.2.4。實現構造函數現在我們要實現兩個參數`Interval`構造函數： ```py from numba.extending import lower_builtin from numba import cgutils @lower_builtin(Interval, types.Float, types.Float) def impl_interval(context, builder, sig, args): typ = sig.return_type lo, hi = args interval = cgutils.create_struct_proxy(typ)(context, builder) interval.lo = lo interval.hi = hi return interval._getvalue() ``` 還有一點在這里發生。 `@lower_builtin`為某些特定的參數類型修飾給定的可調用或操作（這里是`Interval`構造函數）的實現。這允許定義給定操作的特定于類型的實現，這對于重載過多的函數很重要，例如 [`len()`](https://docs.python.org/3/library/functions.html#len "(in Python v3.7)") 。 `types.Float`是所有浮點類型的類（`types.float64`是`types.Float`的實例）。在類上而不是在特定實例上匹配參數類型通常更具有前瞻性（但是，當 _ 返回 _ 類型時 - 主要是在類型推斷階段 - ，您通常必須返回一個類型實例）。由于 Numba 如何傳遞價值，`cgutils.create_struct_proxy()`和`interval._getvalue()`是一個樣板。值作為 [`llvmlite.ir.Value`](http://llvmlite.pydata.org/en/latest/user-guide/ir/values.html#llvmlite.ir.Value "(in llvmlite v0.27.0)") 的實例傳遞，這可能太有限：LLVM 結構值尤其是非常低級別。結構代理是 LLVM 結構值的臨時包裝，允許輕松獲取或設置結構的成員。 `_getvalue()`調用只是從包裝器中獲取 LLVM 值。 ### 6.3.2.5。拳擊和拆箱如果此時嘗試使用`Interval`實例，則肯定會得到錯誤 _“無法將 Interval 轉換為本機值”_。這是因為 Numba 還不知道如何從 Python `Interval`實例創建本機間隔值。讓我們教它如何做到： ```py from numba.extending import unbox, NativeValue @unbox(IntervalType) def unbox_interval(typ, obj, c): """ Convert a Interval object to a native interval structure. """ lo_obj = c.pyapi.object_getattr_string(obj, "lo") hi_obj = c.pyapi.object_getattr_string(obj, "hi") interval = cgutils.create_struct_proxy(typ)(c.context, c.builder) interval.lo = c.pyapi.float_as_double(lo_obj) interval.hi = c.pyapi.float_as_double(hi_obj) c.pyapi.decref(lo_obj) c.pyapi.decref(hi_obj) is_error = cgutils.is_not_null(c.builder, c.pyapi.err_occurred()) return NativeValue(interval._getvalue(), is_error=is_error) ``` _Unbox_ 是“將 Python 對象轉換為本機值”的另一個名稱（它將 Python 對象的想法視為包含簡單本機值的復雜框）。該函數返回一個`NativeValue`對象，該對象使其調用者可以訪問計算的本機值，錯誤位以及可能的其他信息。上面的代碼片段充分利用了`c.pyapi`對象，可以訪問 [Python 解釋器的 C API](https://docs.python.org/3/c-api/index.html) 的子集。注意使用`c.pyapi.err_occurred()`來檢測拆箱時可能發生的任何錯誤（例如嘗試傳遞`Interval('a', 'b')`）。我們還想做反向操作，稱為 _ 拳擊 _，以便從 Numba 函數返回間隔值： ```py from numba.extending import box @box(IntervalType) def box_interval(typ, val, c): """ Convert a native interval structure to an Interval object. """ interval = cgutils.create_struct_proxy(typ)(c.context, c.builder, value=val) lo_obj = c.pyapi.float_from_double(interval.lo) hi_obj = c.pyapi.float_from_double(interval.hi) class_obj = c.pyapi.unserialize(c.pyapi.serialize_object(Interval)) res = c.pyapi.call_function_objargs(class_obj, (lo_obj, hi_obj)) c.pyapi.decref(lo_obj) c.pyapi.decref(hi_obj) c.pyapi.decref(class_obj) return res ``` ## 6.3.3。使用它 [nopython 模式](../glossary.html#term-nopython-mode)函數現在可以使用 Interval 對象以及您在其上定義的各種操作。您可以嘗試以下功能： ```py from numba import jit @jit(nopython=True) def inside_interval(interval, x): return interval.lo <= x < interval.hi @jit(nopython=True) def interval_width(interval): return interval.width @jit(nopython=True) def sum_intervals(i, j): return Interval(i.lo + j.lo, i.hi + j.hi) ``` ## 6.3.4。結論我們已經展示了如何執行以下任務： * 通過繼承`Type`類來定義新的 Numba 類型類 * 為非參數類型定義單例 Numba 類型實例 * 教 Numba 如何使用`typeof_impl.register`推斷某類的 Numba 類型的 Python 值 * 使用`StructModel`和`register_model`定義 Numba 類型的數據模型 * 使用`@box`裝飾器為 Numba 類型實現裝箱功能 * 使用`@unbox`裝飾器和`NativeValue`類為 Numba 類型實現拆箱功能 * 使用`@type_callable`和`@lower_builtin`裝飾器鍵入并實現可調用 * 使用`make_attribute_wrapper`便捷功能公開只讀結構屬性 * 使用`@overload_attribute`裝飾器實現只讀屬性