diff --git a/docs/quick-start/bind.md b/docs/bindings.md similarity index 51% rename from docs/quick-start/bind.md rename to docs/bindings.md index 620d7de5..e35cf364 100644 --- a/docs/quick-start/bind.md +++ b/docs/bindings.md @@ -1,9 +1,13 @@ --- -icon: dot -label: 'Bind native function' -order: 60 +icon: star +title: Write bindings +order: 18 --- +!!! +This document is working in progress. +!!! + pkpy allows to wrap a function pointer as a python function or method that can be called in python code. This function pointer has the following signature: @@ -100,4 +104,105 @@ vm->bind__add__(type, __add__); This specialized binding function has optimizations and result in better performance when calling from python code. -For example, `vm->bind__add__` is preferred over `vm->bind_method<1>(type, "__add__", ...)`. \ No newline at end of file +For example, `vm->bind__add__` is preferred over `vm->bind_method<1>(type, "__add__", ...)`. + +Add `PY_CLASS` macro into your `struct` and implement a static function `_register`. +Inside the `_register` function, you can bind methods and properties to the class. + +```cpp +PY_CLASS(T, mod, name) + +// T is the struct type in cpp +// mod is the module name in python +// name is the class name in python +``` + +## Example + +In this example, we will create a `linalg` module +and implement a `vec2` type with some methods. +And make them available in python just like this. + +```python +from linalg import vec2 + +# construct a vec2 +a = vec2(1.0, 2.0) +b = vec2(0.0, -1.0) + +# add two vec2 +print(a + b) # vec2(1.0, 1.0) + +# set x component +a.x = 8.0 +print(a) # vec2(8.0, 2.0) + +# use dot method +print(a.dot(b)) # -2.0 +``` + +### Implement `Vec2` struct in cpp + +```cpp +struct Vec2{ + float x, y; + Vec2() : x(0.0f), y(0.0f) {} + Vec2(float x, float y) : x(x), y(y) {} + Vec2(const Vec2& v) : x(v.x), y(v.y) {} + Vec2 operator+(const Vec2& v) const { return Vec2(x + v.x, y + v.y); } + float dot(const Vec2& v) const { return x * v.x + y * v.y; } +}; +``` + +### Create `PyVec2` wrapper + +```cpp +struct PyVec2: Vec2 { + PY_CLASS(PyVec2, linalg, vec2) + + PyVec2() : Vec2() {} + PyVec2(const Vec2& v) : Vec2(v) {} + PyVec2(const PyVec2& v) : Vec2(v) {} + + static void _register(VM* vm, PyObject* mod, PyObject* type){ + vm->bind_constructor<3>(type, [](VM* vm, ArgsView args){ + float x = CAST_F(args[1]); + float y = CAST_F(args[2]); + return VAR(Vec2(x, y)); + }); + + vm->bind__repr__(PK_OBJ_GET(Type, type), [](VM* vm, PyObject* obj){ + PyVec2& self = _CAST(PyVec2&, obj); + std::stringstream ss; + ss << "vec2(" << self.x << ", " << self.y << ")"; + return VAR(ss.str()); + }); + + vm->bind__add__(PK_OBJ_GET(Type, type), [](VM* vm, PyObject* obj, PyObject* other){ + PyVec2& self = _CAST(PyVec2&, obj); + PyVec2& other_ = CAST(PyVec2&, other); + return VAR_T(PyVec2, self + other_); + }); + + vm->bind(type, "dot(self, other: vec2) -> float", [](VM* vm, ArgsView args){ + PyVec2& self = _CAST(PyVec2&, args[0]); + PyVec2& other = CAST(PyVec2&, args[1]); + return VAR(self.dot(other)); + }); + } +}; +``` + +### Create `linalg` module + +```cpp +void add_module_linalg(VM* vm){ + PyObject* linalg = vm->new_module("linalg"); + // register PyVec2 + PyVec2::register_class(vm, linalg); +} +``` + +### Further reading + +See [linalg.h](https://github.com/blueloveTH/pocketpy/blob/main/src/linalg.h) for the complete implementation. \ No newline at end of file diff --git a/docs/performance.md b/docs/performance.md index 2fb8a19e..481edcfb 100644 --- a/docs/performance.md +++ b/docs/performance.md @@ -6,13 +6,11 @@ label: Performance # Performance -Currently, pkpy is completely faster than cpython 3.8. -Here is a benchmark result of the current commit. - -Benchmark files are located in `benchmarks/`. - -See [actions/runs](https://github.com/blueloveTH/pocketpy/actions/runs/5113363233/jobs/9192476164). +Currently, pkpy is as fast as cpython 3.8. +**Performance results for cpython 3.8 are applicable to for pkpy.** +Here is a benchmark result of `v1.0.0`. +Files are located in `benchmarks/`. ``` Testing directory: benchmarks/ @@ -47,4 +45,6 @@ Testing directory: benchmarks/ cpython: 0.020165s (100%) pocketpy: 0.004495s (22.29%) ALL TESTS PASSED -``` \ No newline at end of file +``` + +See [actions/runs](https://github.com/blueloveTH/pocketpy/actions/runs/5113363233/jobs/9192476164). \ No newline at end of file diff --git a/docs/plugins.zip b/docs/plugins.zip deleted file mode 100644 index 57ff7e03..00000000 Binary files a/docs/plugins.zip and /dev/null differ diff --git a/docs/quick-start/index.yml b/docs/quick-start/index.yml index ce34a1fa..78fc8917 100644 --- a/docs/quick-start/index.yml +++ b/docs/quick-start/index.yml @@ -1,3 +1,2 @@ icon: rocket -expanded: true order: 20 \ No newline at end of file diff --git a/docs/quick-start/wrap.md b/docs/quick-start/wrap.md deleted file mode 100644 index 23f5205e..00000000 --- a/docs/quick-start/wrap.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -icon: dot -label: 'Wrap native struct' -order: 50 ---- - -Add `PY_CLASS` macro into your `struct` and implement a static function `_register`. -Inside the `_register` function, you can bind methods and properties to the class. - -```cpp -PY_CLASS(T, mod, name) - -// T is the struct type in cpp -// mod is the module name in python -// name is the class name in python -``` - -## Example - -In this example, we will create a `linalg` module -and implement a `vec2` type with some methods. -And make them available in python just like this. - -```python -from linalg import vec2 - -# construct a vec2 -a = vec2(1.0, 2.0) -b = vec2(0.0, -1.0) - -# add two vec2 -print(a + b) # vec2(1.0, 1.0) - -# set x component -a.x = 8.0 -print(a) # vec2(8.0, 2.0) - -# use dot method -print(a.dot(b)) # -2.0 -``` - -### Implement `Vec2` struct in cpp - -```cpp -struct Vec2{ - float x, y; - Vec2() : x(0.0f), y(0.0f) {} - Vec2(float x, float y) : x(x), y(y) {} - Vec2(const Vec2& v) : x(v.x), y(v.y) {} - Vec2 operator+(const Vec2& v) const { return Vec2(x + v.x, y + v.y); } - float dot(const Vec2& v) const { return x * v.x + y * v.y; } -}; -``` - -### Create `PyVec2` wrapper - -```cpp -struct PyVec2: Vec2 { - PY_CLASS(PyVec2, linalg, vec2) - - PyVec2() : Vec2() {} - PyVec2(const Vec2& v) : Vec2(v) {} - PyVec2(const PyVec2& v) : Vec2(v) {} - - static void _register(VM* vm, PyObject* mod, PyObject* type){ - vm->bind_constructor<3>(type, [](VM* vm, ArgsView args){ - float x = CAST_F(args[1]); - float y = CAST_F(args[2]); - return VAR(Vec2(x, y)); - }); - - vm->bind__repr__(PK_OBJ_GET(Type, type), [](VM* vm, PyObject* obj){ - PyVec2& self = _CAST(PyVec2&, obj); - std::stringstream ss; - ss << "vec2(" << self.x << ", " << self.y << ")"; - return VAR(ss.str()); - }); - - vm->bind__add__(PK_OBJ_GET(Type, type), [](VM* vm, PyObject* obj, PyObject* other){ - PyVec2& self = _CAST(PyVec2&, obj); - PyVec2& other_ = CAST(PyVec2&, other); - return VAR_T(PyVec2, self + other_); - }); - - vm->bind(type, "dot(self, other: vec2) -> float", [](VM* vm, ArgsView args){ - PyVec2& self = _CAST(PyVec2&, args[0]); - PyVec2& other = CAST(PyVec2&, args[1]); - return VAR(self.dot(other)); - }); - } -}; -``` - -### Create `linalg` module - -```cpp -void add_module_linalg(VM* vm){ - PyObject* linalg = vm->new_module("linalg"); - // register PyVec2 - PyVec2::register_class(vm, linalg); -} -``` - -### Further reading - -See [linalg.h](https://github.com/blueloveTH/pocketpy/blob/main/src/linalg.h) for the complete implementation. \ No newline at end of file