adding python bindings to the library

.github/workflows/ci.yaml → .github/workflows/library.yaml

@@ -1,4 +1,4 @@
-name: CI
+name: Library
 
 on:
   pull_request:
@@ -13,21 +13,22 @@ env:
 
 jobs:
   build:
-    name: Build library
+    name: Build
     runs-on: ubuntu-latest
     strategy:
       matrix:
         cc: [gcc, clang]
     container:
-      image: andrelcmoreira/pool-day:v2
+      image: andrelcmoreira/pool-day:v3
       volumes:
         - ${{ github.workspace }}:/pool-day
       credentials:
         username: ${{ secrets.DOCKERHUB_USER }}
         password: ${{ secrets.DOCKERHUB_PASS }}
     steps:
       - uses: actions/checkout@v2
-      - name: Build library
+
+      - name: Build
         run: |
           cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_C_COMPILER=${{ matrix.cc }} -S . -B build
           cmake --build build
@@ -36,14 +37,15 @@ jobs:
     name: Build samples
     runs-on: ubuntu-latest
     container:
-      image: andrelcmoreira/pool-day:v2
+      image: andrelcmoreira/pool-day:v3
       volumes:
         - ${{ github.workspace }}:/pool-day
       credentials:
         username: ${{ secrets.DOCKERHUB_USER }}
         password: ${{ secrets.DOCKERHUB_PASS }}
     steps:
       - uses: actions/checkout@v2
+
       - name: Build samples
         run: |
           cmake -DCMAKE_BUILD_TYPE=Debug -DBUILD_SAMPLES=ON -S . -B build
@@ -54,7 +56,7 @@ jobs:
     runs-on: ubuntu-latest
     needs: build
     container:
-      image: andrelcmoreira/pool-day:v2
+      image: andrelcmoreira/pool-day:v3
       volumes:
         - ${{ github.workspace }}:/pool-day
       credentials:
@@ -92,7 +94,7 @@ jobs:
     runs-on: ubuntu-latest
     needs: unit_tests
     container:
-      image: andrelcmoreira/pool-day:v2
+      image: andrelcmoreira/pool-day:v3
       volumes:
         - ${{ github.workspace }}:/pool-day
       credentials:
@@ -113,14 +115,15 @@ jobs:
     name: Check documentation
     runs-on: ubuntu-latest
     container:
-      image: andrelcmoreira/pool-day:v2
+      image: andrelcmoreira/pool-day:v3
       volumes:
         - ${{ github.workspace }}:/pool-day
       credentials:
         username: ${{ secrets.DOCKERHUB_USER }}
         password: ${{ secrets.DOCKERHUB_PASS }}
     steps:
       - uses: actions/checkout@v2
+
       - name: Build library documentation
         run: |
           cmake -DBUILD_DOCUMENTATION=ON -S . -B build
@@ -131,7 +134,7 @@ jobs:
     runs-on: ubuntu-latest
     needs: unit_tests
     container:
-      image: andrelcmoreira/pool-day:v2
+      image: andrelcmoreira/pool-day:v3
       volumes:
         - ${{ github.workspace }}:/pool-day
       credentials:

.github/workflows/python.yaml

@@ -0,0 +1,45 @@
+name: Python bindings
+
+on:
+  pull_request:
+    push:
+      branches:
+        - develop
+
+env:
+  PYLINT_MINIMUM_RATE: 9
+
+jobs:
+  build:
+    name: Build python package
+    runs-on: ubuntu-latest
+    container:
+      image: andrelcmoreira/pool-day:v3
+      volumes:
+        - ${{ github.workspace }}:/pool-day
+      credentials:
+        username: ${{ secrets.DOCKERHUB_USER }}
+        password: ${{ secrets.DOCKERHUB_PASS }}
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Build package
+        run: |
+          cd python
+          pip install . --break-system-packages
+
+  lint:
+    name: Lint the python bindings
+    runs-on: ubuntu-latest
+    container:
+      image: andrelcmoreira/pool-day:v3
+      volumes:
+        - ${{ github.workspace }}:/pool-day
+      credentials:
+        username: ${{ secrets.DOCKERHUB_USER }}
+        password: ${{ secrets.DOCKERHUB_PASS }}
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Run pylint
+        run: pylint --rcfile python/pylintrc python/pool_day --fail-under ${{ env.PYLINT_MINIMUM_RATE }}

CMakeLists.txt

@@ -7,6 +7,7 @@ option(BUILD_UNIT_TESTS "build the unit tests of the library" OFF)
 option(BUILD_DOCUMENTATION "build the documentation of the library" OFF)
 option(BUILD_COVERAGE "build the coverage data" OFF)
 option(ENABLE_LOGGING "enable library logs" OFF)
+option(BUILD_PYTHON_BINDINGS "build the library's python bindings" OFF)
 
 set(PROJECT_NAME "pool-day")
 set(SOURCES src/task.c src/queue.c src/pool_day.c)
@@ -45,6 +46,10 @@ if(ENABLE_LOGGING)
   list(APPEND SOURCES "src/logger.c")
 endif(ENABLE_LOGGING)
 
+if(BUILD_PYTHON_BINDINGS)
+  add_subdirectory(python)
+endif(BUILD_PYTHON_BINDINGS)
+
 add_library(${PROJECT_NAME} SHARED ${SOURCES})
 target_link_libraries(${PROJECT_NAME} pthread)
 

Dockerfile

@@ -5,7 +5,7 @@ RUN apt install cmake gcc g++ clang -y # building tools
 RUN apt install doxygen python3 python3-pip -y # utils
 RUN apt install cppcheck gcovr valgrind -y # qa tools
 RUN apt install libgmock-dev libgtest-dev -y # frameworks
-RUN pip3 install --break-system-packages cpplint # python packages
+RUN pip3 install --break-system-packages cpplint pylint # python packages
 
 WORKDIR /pool-day
 

README.md

@@ -20,10 +20,11 @@ $ sudo cmake --install build
 Additional flags can be supplied as parameter to cmake according to the table
 below:
 
-|      Flag      |                 Description          |
-|----------------|--------------------------------------|
-|  BUILD_SAMPLES | Build the library's samples          |
-| ENABLE_LOGGING | Enable the library's logging feature |
+|        Flag         |                 Description            |
+|---------------------|----------------------------------------|
+|    BUILD_SAMPLES    | Build the library's samples            |
+|   ENABLE_LOGGING    | Enable the library's logging feature   |
+|BUILD_PYTHON_BINDINGS| Build the library's python bindings    |
 
 #### Support
 

python/CMakeLists.txt

@@ -0,0 +1,4 @@
+#cmake_minimum_required(VERSION 3.18)
+#
+#find_package(Python3 COMPONENTS Interpreter Development REQUIRED)
+# TODO

python/pool_day/__init__.py

@@ -0,0 +1,6 @@
+from pool_day.c_defs import pool_day_callback
+from .pool_day import create_pool, create_task, PoolDay, TaskResult
+
+
+__all__ = ['PoolDay', 'TaskResult', 'create_pool', 'create_task',
+           'pool_day_callback']

python/pool_day/c_defs.py

@@ -0,0 +1,86 @@
+from ctypes import CDLL as cdll
+from ctypes import POINTER as c_pointer
+from ctypes import CFUNCTYPE as c_func_type
+from ctypes import cast
+from ctypes import byref
+from ctypes import (
+    Structure,
+    c_int,
+    c_uint32,
+    c_void_p,
+    c_int,
+    c_size_t,
+)
+from dataclasses import dataclass
+from typing import Any
+
+
+class CPoolDay(Structure):
+    pass
+
+
+class CTask(Structure):
+    pass
+
+
+@dataclass
+class TaskResult:
+    result: Any
+
+
+def pool_day_callback(cb):
+
+    @c_func_type(c_void_p, c_void_p)
+    def _cb(param):
+        ret = cb(param)
+
+        print('pool_day_callback ret:', ret)
+        print('pool_day_callback ret type:', type(ret))
+        print('pool_day_callback param value:', param)
+        print('pool_day_callback param type:', type(param))
+
+        return ret
+
+    return _cb
+
+
+def to_result(ptr: c_void_p) -> TaskResult:
+    return TaskResult(result=ptr)
+
+
+_pd_handle = cdll('/usr/lib/libpool-day.so')
+
+# create_pool
+_pd_handle.create_pool.argtypes = [c_uint32]
+_pd_handle.create_pool.restype = c_pointer(CPoolDay)
+
+# destroy_pool
+_pd_handle.destroy_pool.argtypes = [c_void_p]
+_pd_handle.destroy_pool.restype = c_int
+
+# abort_tasks
+_pd_handle.abort_tasks.argtypes = [c_pointer(CPoolDay)]
+_pd_handle.abort_tasks.restype = c_int
+
+# enqueue_task
+_pd_handle.enqueue_task.argtypes = [c_pointer(CPoolDay), c_pointer(CTask)]
+_pd_handle.enqueue_task.restype = c_int
+
+# queued_tasks
+_pd_handle.queued_tasks.argtypes = [c_pointer(CPoolDay)]
+_pd_handle.queued_tasks.restype = c_uint32
+
+# create_sync_task
+_pd_handle.create_sync_task.argtypes = [c_uint32, c_void_p, c_void_p, c_size_t]
+_pd_handle.create_sync_task.restype = c_pointer(CTask)
+
+# create_async_task
+_pd_handle.create_async_task.argtypes = [c_uint32, c_void_p, c_void_p, c_size_t, c_void_p, c_void_p]
+_pd_handle.create_async_task.restype = c_pointer(CTask)
+
+# wait_task_finish
+_pd_handle.wait_task_finish.argtypes = [c_pointer(CTask)]
+_pd_handle.wait_task_finish.restype = c_void_p
+
+# get_task_result
+_pd_handle.get_task_result.argtypes = [c_pointer(CTask)]

python/pool_day/pool_day.py

@@ -0,0 +1,99 @@
+from contextlib import contextmanager
+from ctypes import byref
+
+from pool_day.c_defs import _pd_handle, CTask, CPoolDay, TaskResult, to_result
+
+
+# TODO: task return
+
+
+class PoolDay:
+
+    """
+    PoolDay instance.
+
+    Implements a wrapper around the pool-day C library.
+    """
+
+    def __init__(self, pool: CPoolDay):
+        """
+        Initialize the PoolDay instance.
+
+        :pool: The pool structure instance.
+        """
+        self._pool = pool
+
+    def enqueue_task(self, task: CTask) -> int:
+        """
+        Enqueue a task to the pool.
+
+        :task: The task instance.
+        :return: 0 on success, the suitable error code on failure.
+        """
+        return _pd_handle.enqueue_task(self._pool, task)
+
+    def abort_tasks(self) -> int:
+        """
+        Abort all pending tasks in the pool.
+
+        :return: 0 on success, the suitable error code on failure.
+        """
+        return _pd_handle.abort_tasks(self._pool)
+
+    def queued_tasks(self) -> int:
+        """
+        Get the number of queued tasks in the pool.
+
+        :return: Number of queued tasks.
+        """
+        return _pd_handle.queued_tasks(self._pool)
+
+    def wait_task_finish(self, task: CTask) -> None:
+        """
+        Wait for a task to finish.
+
+        :task: The task instance.
+        """
+        _pd_handle.wait_task_finish(self._pool, task)
+
+    def get_task_result(self, task: CTask) -> TaskResult:
+        """
+        Get a task result.
+
+        :task: The task instance.
+        :return: The return value of the task's callback function.
+        """
+        ret = _pd_handle.get_task_result(self._pool, task)
+
+        print(f'get_task_result ret: {ret}')
+
+        return to_result(ret)
+
+
+def create_sync_task(cb, param) -> CTask:
+    """
+    Create a new sync task instance.
+
+    :cb: The callback function.
+    :param: The parameter passed to the callback function.
+
+    :return: A new task instance.
+    """
+    return _pd_handle.create_sync_task(cb, param)
+
+
+# TODO: create_async_task
+
+
+@contextmanager
+def create_pool(size: int):
+    """
+    Create a new pool instance.
+
+    :size: Number of threads in the pool.
+
+    :return: A pool-day instance.
+    """
+    pool = _pd_handle.create_pool(size)
+    yield PoolDay(pool)
+    _pd_handle.destroy_pool(byref(pool))

python/pylintrc

@@ -0,0 +1,2 @@
+[MESSAGES CONTROL]
+disable=too-few-public-methods