gh-218: add ops impl for a package with built-in ops

include/spla.h

@@ -113,6 +113,7 @@ typedef void(spla_MessageCallback)(spla_Status, const char* message, const char*
 /* Library configuration and accessors */
 
 SPLA_API void        spla_Library_finalize();
+SPLA_API spla_Status spla_Library_initialize();
 SPLA_API spla_Status spla_Library_set_accelerator(spla_AcceleratorType accelerator);
 SPLA_API spla_Status spla_Library_set_platform(int index);
 SPLA_API spla_Status spla_Library_set_device(int index);
@@ -125,9 +126,10 @@ SPLA_API spla_Status spla_Library_get_accelerator_info(char* buffer, int length)
 
 /* Built-in predefined scalar values types for storage parametrization  */
 
-SPLA_API spla_Type spla_Type_int();
-SPLA_API spla_Type spla_Type_uint();
-SPLA_API spla_Type spla_Type_float();
+SPLA_API spla_Type spla_Type_BOOL();
+SPLA_API spla_Type spla_Type_INT();
+SPLA_API spla_Type spla_Type_UINT();
+SPLA_API spla_Type spla_Type_FLOAT();
 
 //////////////////////////////////////////////////////////////////////////////////////
 

include/spla/ref.hpp

@@ -203,6 +203,10 @@ namespace spla {
             return m_object;
         }
 
+        T* ref_and_get() {
+            return safe_ref(m_object);
+        }
+
         template<typename G>
         [[nodiscard]] bool is() const {
             return !m_object || dynamic_cast<G*>(m_object);

python/pyspla/__init__.py

@@ -69,9 +69,9 @@
 managed by container internally. All required format conversion done
 in the context of particular primitive usage.
 
-- `Matrix` - Generalized statically-typed sparse storage-invariant matrix primitive.
-- `Vector` - Generalized statically-typed sparse storage-invariant vector primitive.
-- `Scalar` - Generalized statically-typed scalar primitive.
+- `Matrix`. Generalized statically-typed sparse storage-invariant matrix primitive.
+- `Vector`. Generalized statically-typed sparse storage-invariant vector primitive.
+- `Scalar`. Generalized statically-typed scalar primitive.
 
 Schedule
 --------
@@ -80,8 +80,8 @@
 control the order of the tasks' execution, parallel execution of tasks
 on some level, notification on some steps completion and etc.
 
-- `Schedule` - Schedule object which may be executed by library.
-- `Task` - A particular wort to be done inside a step of schedule.
+- `Schedule`. Schedule object which may be executed by library.
+- `Task`. A particular wort to be done inside a step of schedule.
 
 Types
 -----
@@ -92,33 +92,48 @@
 can interpret stored data as her/she wants. Spla types set is limited due to the nature
 of GPUs accelerations, where arbitrary layout of data causes significant performance penalties.
 
-- `INT`   - 4-byte-sized signed integral value
-- `UINT`  - 4-byte-sized unsigned integral value
-- `FLOAT` - 4-byte-sized single-precision floating point value
+- `BOOL`. 4-byte-sized signed logical value (auxiliary type).
+- `INT`. 4-byte-sized signed integral value.
+- `UINT`. 4-byte-sized unsigned integral value.
+- `FLOAT`. 4-byte-sized single-precision floating point value.
 
-Op
---
+Operations
+----------
 
 Library provides a set of unary, binary and select ops for values data manipulation inside
-matrix and vector containers.
-
-- `PLUS`   - binary(x,y): r = x + y
-- `MINUS`  - binary(x,y): r = x - y
-- `MULT`   - binary(x,y): r = x * y
-- `DIV`    - binary(x,y): r = x / y
-- `FIRST`  - binary(x,y): r = x
-- `SECOND` - binary(x,y): r = y
-- `ONE`    - binary(x,y): r = 1
-- `MIN`    - binary(x,y): r = min(x, y)
-- `MAX`    - binary(x,y): r = max(x, y)
-- `BOR`    - binary(x,y): r = x | y, for integral only
-- `BAND`   - binary(x,y): r = x & y, for integral only
-- `BXOR`   - binary(x,y): r = x ^ y, for integral only
-
-Usage information
------------------
-
-TBD.
+matrix and vector containers. Unary operations commonly used for apply and transformation
+operations, binary operations used for reductions and products, select operations used for
+filtration and mask application.
+
+List of built-in binary operations:
+
+Name | Type | Meaning
+---  | ---  | ---
+`PLUS`   | binary(x,y) | r = x + y
+`MINUS`  | binary(x,y) | r = x - y
+`MULT`   | binary(x,y) | r = x * y
+`DIV`    | binary(x,y) | r = x / y
+`FIRST`  | binary(x,y) | r = x
+`SECOND` | binary(x,y) | r = y
+`ONE`    | binary(x,y) | r = 1
+`MIN`    | binary(x,y) | r = min(x, y)
+`MAX`    | binary(x,y) | r = max(x, y)
+`BOR`    | binary(x,y) | r = x | y, for integral only
+`BAND`   | binary(x,y) | r = x & y, for integral only
+`BXOR`   | binary(x,y) | r = x ^ y, for integral only
+
+List of built-in select operations:
+
+Name | Type | Meaning
+---  | ---  | ---
+`EQZERO` | select(x) | x == 0
+`NQZERO` | select(x) | x != 0
+`GTZERO` | select(x) | x > 0
+`GEZERO` | select(x) | x >= 0
+`LTZERO` | select(x) | x < 0
+`LEZERO` | select(x) | x <= 0
+`ALWAYS` | select(x) | true
+`NEVER`  | select(x) | false
 
 Details
 -------
@@ -167,17 +182,19 @@
 from .scalar import *
 from .version import *
 
-if not bridge.is_docs():
-    for t in BUILT_IN:
-        t._setup()
-
 __version__ = VERSIONS[-1]
 
 __all__ = [
     "Type",
+    "BOOL",
     "INT",
     "UINT",
     "FLOAT",
+    "Op",
+    "OpUnary",
+    "OpBinary",
+    "OpSelect",
+    "MemView",
     "Object",
     "Array",
     "Matrix",

python/pyspla/array.py

@@ -178,7 +178,7 @@ def get(self, index):
 
         value = self._dtype._c_type(0)
         check(self._dtype._array_get(self._hnd, ctypes.c_uint(index), ctypes.byref(value)))
-        return self._dtype.to_py(value)
+        return self._dtype.cast_value(value)
 
     def build(self, view: MemView):
         """

python/pyspla/bridge.py

@@ -59,6 +59,10 @@ class SplaError(Exception):
     pass
 
 
+class SplaFailedInitialize(SplaError):
+    pass
+
+
 class SplaNoAcceleration(SplaError):
     pass
 
@@ -133,6 +137,8 @@ def load_library(lib_path):
 
     _spla.spla_Library_finalize.restype = None
     _spla.spla_Library_finalize.argtypes = []
+    _spla.spla_Library_initialize.restype = _status_t
+    _spla.spla_Library_initialize.argtypes = []
     _spla.spla_Library_set_accelerator.restype = _status_t
     _spla.spla_Library_set_accelerator.argtypes = [_enum_t]
     _spla.spla_Library_set_platform.restype = _status_t
@@ -148,12 +154,14 @@ def load_library(lib_path):
     _spla.spla_Library_get_accelerator_info.restype = _status_t
     _spla.spla_Library_get_accelerator_info.argtypes = [ctypes.c_char_p, _int]
 
-    _spla.spla_Type_int.restype = _object_t
-    _spla.spla_Type_int.argtypes = []
-    _spla.spla_Type_uint.restype = _object_t
-    _spla.spla_Type_uint.argtypes = []
-    _spla.spla_Type_float.restype = _object_t
-    _spla.spla_Type_float.argtypes = []
+    _spla.spla_Type_BOOL.restype = _object_t
+    _spla.spla_Type_BOOL.argtypes = []
+    _spla.spla_Type_INT.restype = _object_t
+    _spla.spla_Type_INT.argtypes = []
+    _spla.spla_Type_UINT.restype = _object_t
+    _spla.spla_Type_UINT.argtypes = []
+    _spla.spla_Type_FLOAT.restype = _object_t
+    _spla.spla_Type_FLOAT.argtypes = []
 
     _spla.spla_OpBinary_PLUS_INT.restype = _object_t
     _spla.spla_OpBinary_PLUS_UINT.restype = _object_t
@@ -410,6 +418,12 @@ def default_callback(status, msg, file, function, line, user_data):
     print(f"pyspla: [{decoded_file}:{line}] {_status_mapping[status]}: {decoded_msg}")
 
 
+def init_library():
+    if _spla:
+        if _spla.spla_Library_initialize() != 0:
+            raise SplaFailedInitialize
+
+
 def finalize():
     if _spla:
         _spla.spla_Library_finalize()
@@ -444,6 +458,8 @@ def initialize():
         raise Exception(f"no compiled spla file {TARGET} to load")
 
     load_library(_spla_path)
+    init_library()
+
     _default_callback = _callback_t(default_callback)
 
     try:

python/pyspla/object.py

@@ -74,8 +74,16 @@ def __del__(self):
         if self._hnd:
             check(backend().spla_RefCnt_unref(self._hnd))
 
-    def set_label(self, label):
-        self._label = label
+    @property
+    def hnd(self):
+        """
+        Return handle (ctypes.c_void_p) to a wrapped native C object.
+        """
+        return self._hnd
 
-    def get_label(self):
+    @property
+    def label(self):
+        """
+        Returns optional debug string label for the object.
+        """
         return self._label