# 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`裝飾器實現只讀屬性
- 1. 用戶手冊
- 1.1。 Numba 的約 5 分鐘指南
- 1.2。概述
- 1.3。安裝
- 1.4。使用@jit 編譯 Python 代碼
- 1.5。使用@generated_jit 進行靈活的專業化
- 1.6。創建 Numpy 通用函數
- 1.7。用@jitclass 編譯 python 類
- 1.8。使用@cfunc 創建 C 回調
- 1.9。提前編譯代碼
- 1.10。使用@jit 自動并行化
- 1.11。使用@stencil裝飾器
- 1.12。從 JIT 代碼 中回調到 Python 解釋器
- 1.13。性能提示
- 1.14。線程層
- 1.15。故障排除和提示
- 1.16。常見問題
- 1.17。示例
- 1.18。會談和教程
- 2. 參考手冊
- 2.1。類型和簽名
- 2.2。即時編譯
- 2.3。提前編譯
- 2.4。公用事業
- 2.5。環境變量
- 2.6。支持的 Python 功能
- 2.7。支持的 NumPy 功能
- 2.8。與 Python 語義的偏差
- 2.9。浮點陷阱
- 2.10。 Python 2.7 壽命終止計劃
- 3. 用于 CUDA GPU 的 Numba
- 3.1。概述
- 3.2。編寫 CUDA 內核
- 3.3。內存管理
- 3.4。編寫設備功能
- 3.5。 CUDA Python 中支持的 Python 功能
- 3.6。支持的原子操作
- 3.7。隨機數生成
- 3.8。設備管理
- 3.10。示例
- 3.11。使用 CUDA 模擬器 調試 CUDA Python
- 3.12。 GPU 減少
- 3.13。 CUDA Ufuncs 和廣義 Ufuncs
- 3.14。共享 CUDA 內存
- 3.15。 CUDA 陣列接口
- 3.16。 CUDA 常見問題
- 4. CUDA Python 參考
- 4.1。 CUDA 主機 API
- 4.2。 CUDA 內核 API
- 4.3。內存管理
- 5. 用于 AMD ROC GPU 的 Numba
- 5.1。概述
- 5.2。編寫 HSA 內核
- 5.3。內存管理
- 5.4。編寫設備功能
- 5.5。支持的原子操作
- 5.6。代理商
- 5.7。 ROC Ufuncs 和廣義 Ufuncs
- 5.8。示例
- 6. 擴展 Numba
- 6.1。高級擴展 API
- 6.2。低級擴展 API
- 6.3。示例:間隔類型
- 7. 開發者手冊
- 7.1。貢獻給 Numba
- 7.2。 Numba 建筑
- 7.3。多態調度
- 7.4。關于發電機的注意事項
- 7.5。關于 Numba Runtime 的注意事項
- 7.6。使用 Numba Rewrite Pass 獲得樂趣和優化
- 7.7。實時變量分析
- 7.8。上市
- 7.9。模板注釋
- 7.10。關于自定義管道的注意事項
- 7.11。環境對象
- 7.12。哈希 的注意事項
- 7.13。 Numba 項目路線圖
- 8. Numba 增強建議
- 9. 術語表