Add 'xo-pyutil/' from commit 'a2cb8ae60f'

git-subtree-dir: xo-pyutil
git-subtree-mainline: 219038c445
git-subtree-split: a2cb8ae60f

xo-pyutil/.gitignore

@@ -0,0 +1,8 @@
+# emacs project config
+.projectile
+# clangd working space (see emacs+lsp)
+.cache
+# typical cmake build directory (source-tree-nephew)
+.build*
+# symlink to builddir/compile_commands.json;  should be set manually in dev sandbox
+compile_commands.json

xo-pyutil/CMakeLists.txt

@@ -0,0 +1,45 @@
+# pyutil/CMakeLists.txt
+
+cmake_minimum_required(VERSION 3.10)
+
+project(xo_pyutil VERSION 0.1)
+
+include(GNUInstallDirs)
+include(cmake/xo-bootstrap-macros.cmake)   # very little to unit test here
+
+xo_cxx_toplevel_options2()
+
+# ----------------------------------------------------------------
+# cmake -DCMAKE_BUILD_TYPE=coverage
+xo_toplevel_coverage_config2()
+
+# ----------------------------------------------------------------
+# cmake -DCMAKE_BUILD_TYPE=debug
+xo_toplevel_debug_config2()
+
+# ----------------------------------------------------------------
+# bespoke (usually temporary) c++ settings
+
+set(PROJECT_CXX_FLAGS "")
+#set(PROJECT_CXX_FLAGS "-fconcepts-diagnostics-depth=2")
+add_definitions(${PROJECT_CXX_FLAGS})
+
+# ----------------------------------------------------------------
+
+# ----------------------------------------------------------------
+
+set(SELF_LIB xo_pyutil)
+
+xo_add_headeronly_library(${SELF_LIB})
+xo_install_library4(${SELF_LIB} ${PROJECT_NAME}Targets)
+xo_export_cmake_config(${PROJECT_NAME} ${PROJECT_VERSION} ${PROJECT_NAME}Targets)
+
+# ----------------------------------------------------------------
+
+add_subdirectory(example)
+#add_subdirectory(utest)
+
+# ----------------------------------------------------------------
+# install any additional components
+
+#install(TARGETS ex1 DESTINATION bin/${PROJECT_NAME}/example)

xo-pyutil/README.md

@@ -0,0 +1,25 @@
+# pybind11 utilities for XO projects
+
+## Getting Started
+
+### build + install dependencies
+
+- see [github/Rconybea/xo-cmake](https://github.com/Rconybea/xo-cmake)
+
+### to build + install locally
+
+```
+$ cd xo-pyutil
+$ mkdir build
+$ cd build
+$ PREFIX=/usr/local # for example
+$ cmake -DCMAKE_MODULE_PATH=${PREFIX}/share/cmake -DCMAKE_PREFIX_PATH=$(PREFIX) -DCMAKE_INSTALL_PREFIX=${PREFIX} ..
+$ make
+$ make install
+```
+
+### LSP support
+```
+$ cd xo-pyutil
+$ ln -s build/compile_commands.json  # lsp will look for compile_commands.json in the root of the source tree
+```

xo-pyutil/cmake/xo-bootstrap-macros.cmake

@@ -0,0 +1,35 @@
+# ----------------------------------------------------------------
+# for example:
+#   $ PREFIX=/usr/local   # for example
+#   $ cmake -DCMAKE_MODULE_PATH=prefix -DCMAKE_INSTALL_PREFIX=$PREFIX -B .build
+#
+# will get
+#   CMAKE_MODULE_PATH
+# from xo-cmake-config --cmake-module-path
+#
+# and expect .cmake macros in
+#   CMAKE_MODULE_PATH/xo_macros/xo_cxx.cmake
+# ----------------------------------------------------------------
+
+find_program(XO_CMAKE_CONFIG_EXECUTABLE NAMES xo-cmake-config REQUIRED)
+
+if ("${XO_CMAKE_CONFIG_EXECUTABLE}" STREQUAL "XO_CMAKE_CONFIG_EXECUTABLE-NOT_FOUND")
+    message(FATAL "could not find xo-cmake-config executable")
+endif()
+
+message(STATUS "XO_CMAKE_CONFIG_EXECUTABLE=${XO_CMAKE_CONFIG_EXECUTABLE}")
+
+if (NOT XO_SUBMODULE_BUILD)
+    if (("${CMAKE_MODULE_PATH}" STREQUAL "") OR ("${CMAKE_MODULE_PATH}" STREQUAL prefix))
+        # default to typical install location for xo-project-macros
+        execute_process(COMMAND ${XO_CMAKE_CONFIG_EXECUTABLE} --cmake-module-path OUTPUT_VARIABLE CMAKE_MODULE_PATH)
+        message(STATUS "CMAKE_MODULE_PATH=${CMAKE_MODULE_PATH}")
+    endif()
+endif()
+
+# needs to have been installed somewhere on CMAKE_MODULE_PATH,
+# (e.g. from xo-cmake with the same value for CMAKE_INSTALL_PREFIX)
+#
+include(xo_macros/xo_cxx)
+
+xo_cxx_bootstrap_message()

xo-pyutil/cmake/xo_pyutilConfig.cmake.in

@@ -0,0 +1,4 @@
+@PACKAGE_INIT@
+
+include("${CMAKE_CURRENT_LIST_DIR}/@PROJECT_NAME@Targets.cmake")
+check_required_components("@PROJECT_NAME@")

xo-pyutil/example/CMakeLists.txt

@@ -0,0 +1 @@
+add_subdirectory(ex1)

xo-pyutil/example/ex1/CMakeLists.txt

@@ -0,0 +1,11 @@
+# xo-pyutil/example/ex1/CMakeLists.txt
+
+set(SELF_LIB xo_pyutilexample)
+set(SELF_SRCS pyex1.cpp)
+
+if (XO_ENABLE_EXAMPLES)
+    xo_pybind11_library(${SELF_LIB} ${PROJECT_NAME}Targets ${SELF_SRCS})
+    xo_pybind11_dependency(${SELF_LIB} refcnt)
+endif()
+
+# end CMakeLists.txt

xo-pyutil/example/ex1/pyex1.cpp

@@ -0,0 +1,14 @@
+/* @file pyex1.cpp */
+
+#include "pyutilexample.hpp"
+#include "xo/pyutil/pyutil.hpp"
+#include <cmath>
+
+namespace xo {
+
+    PYBIND11_MODULE(XO_PYUTILEXAMPLE_MODULE_NAME(), m) {
+        m.def("sqrt", [](double x) { return ::sqrt(x); });
+    }
+}
+
+/* end pyex1.cpp */

xo-pyutil/example/ex1/pyutilexample.hpp.in

@@ -0,0 +1,21 @@
+/* @file pyutilexample.hpp */
+
+/* python requires module name = library name
+ * example:
+ *   PYBIND11_MODULE(XO_PYUTILEXAMPLE_MODULE_NAME(), m) { ... }
+ */
+#define XO_PYUTILEXAMPLE_MODULE_NAME() @SELF_LIB@
+
+/* example:
+ *   py::module_::import(XO_PYUTILEXAMPLE_MODULE_NAME_STR)
+ */
+#define XO_PYUTILEXAMPLE_MODULE_NAME_STR "@SELF_LIB@"
+
+/* example:
+ *   XO_PYUTILEXAMPLE_IMPORT_MODULE()
+ * replaces
+ *   py::module_::import("xo_pyexpression")
+ */
+#define XO_PYUTILEXAMPLE_IMPORT_MODULE() py::module_::import("@SELF_LIB@")
+
+/* end pyutilexample.hpp */

xo-pyutil/include/xo/pyutil/pycaller.hpp

@@ -0,0 +1,153 @@
+/** @file pycaller.hpp
+ *
+ *  Author: Roland Conybeare
+ **/
+
+#pragma once
+
+#include <pybind11/pybind11.h>
+
+//#include <cstdint>
+
+namespace xo {
+    namespace pyutil {
+        struct pycaller_base {
+            using void_function_type = void (*)();
+            using factory_function_type = pycaller_base*(*)(void_function_type);
+
+            virtual ~pycaller_base() = default;
+
+            /* note: need inherited class pycaller_base revealed to pybind11 too */
+            static pybind11::module & declare_once(pybind11::module & m) {
+                static bool s_once = false;
+                if (!s_once) {
+                    s_once = true;
+                    pybind11::class_<pycaller_base>(m, "pycaller_base");
+                }
+                return m;
+            }
+        };
+
+        /** @class pycaller
+         *  @brief Invoke function pointer of type Retval(*)(Args...) from py::object
+         *
+         *  Arguments converted from py::object, and return type converted back to py::object.
+         *
+         *  Each distinct combination of {Retval,Args...} needs to be established at compile time
+         *  (since we need PyCall<Retval, Args...> to be instantiated for particular types)
+         *
+         *  Use when we don't know function pointer until *runtime*,
+         *  for example getting function pointer from just-compiled code using xo-pyjit
+         **/
+        template <typename Retval, typename... Args>
+        struct pycaller;
+
+        template <typename Retval>
+        struct pycaller<Retval> : public pycaller_base {
+            using self_type = pycaller<Retval>;
+            using function_type = Retval (*)();
+            using void_function_type = void (*)();
+
+            pycaller(void_function_type addr) : fptr_{reinterpret_cast<function_type>(addr)} {}
+
+            static pycaller_base * make(void_function_type addr) { return new pycaller(addr); }
+
+            /* note: prototype_str must be [const char *],  pybind11 requirement */
+            static pybind11::module & declare_once(pybind11::module & m,
+                                                   const char * prototype_str) {
+                static bool s_once = false;
+                if (!s_once) {
+                    s_once = true;
+                    pycaller_base::declare_once(m);
+                    pybind11::class_<self_type, pycaller_base>(m, prototype_str)
+                        .def("__call__",
+                             [](self_type & self)
+                                 {
+                                     return pybind11::cast((*self.fptr_)());
+                                 });
+                }
+                return m;
+            }
+
+            pybind11::object operator()() { return pybind11::cast((*fptr_)()); }
+
+        private:
+            function_type fptr_;
+        };
+
+        template <typename Retval, typename Arg1>
+        struct pycaller<Retval, Arg1> : public pycaller_base {
+            using self_type = pycaller<Retval, Arg1>;
+            using function_type = Retval (*)(Arg1);
+            using void_function_type = void (*)();
+
+            pycaller(void_function_type addr) : fptr_{reinterpret_cast<function_type>(addr)} {}
+
+            static pycaller_base * make(void_function_type addr) { return new pycaller(addr); }
+
+            /* note: prototype_str must be [const char *],  pybind11 requirement */
+            static pybind11::module & declare_once(pybind11::module & m,
+                                                   const char * prototype_str) {
+                static bool s_once = false;
+                if (!s_once) {
+                    s_once = true;
+                    pycaller_base::declare_once(m);
+                    pybind11::class_<self_type, pycaller_base>(m, prototype_str)
+                        .def("__call__",
+                             [](self_type & self, Arg1 arg1)
+                                 {
+                                     return pybind11::cast((*self.fptr_)(arg1));
+                                 })
+                        ;
+                }
+                return m;
+            }
+
+            pybind11::object operator()(pybind11::object arg1) {
+                return pybind11::cast((*fptr_)(pybind11::cast<Arg1>(arg1)));
+            }
+
+        private:
+            function_type fptr_;
+        };
+
+        template <typename Retval, typename Arg1, typename Arg2>
+        struct pycaller<Retval, Arg1, Arg2> : public pycaller_base {
+            using self_type = pycaller<Retval, Arg1, Arg2>;
+            using function_type = Retval (*)(Arg1, Arg2);
+            using void_function_type = void (*)();
+
+            pycaller(void_function_type addr) : fptr_{reinterpret_cast<function_type>(addr)} {}
+
+            static pycaller_base * make(void_function_type addr) { return new pycaller(addr); }
+
+            /* note: prototype_str must be [const char *],  pybind11 requirement */
+            static pybind11::module & declare_once(pybind11::module & m,
+                                                   const char * prototype_str) {
+                static bool s_once = false;
+                if (!s_once) {
+                    s_once = true;
+                    pycaller_base::declare_once(m);
+                    pybind11::class_<self_type, pycaller_base>(m, prototype_str)
+                        .def("__call__",
+                             [](self_type & self, Arg1 arg1, Arg2 arg2)
+                                 {
+                                     return pybind11::cast((*self.fptr_)(arg1, arg2));
+                                 })
+                        ;
+                }
+                return m;
+            }
+
+            pybind11::object operator()(pybind11::object arg1, pybind11::object arg2) {
+                return pybind11::cast((*fptr_)(pybind11::cast<Arg1>(arg1),
+                                               pybind11::cast<Arg2>(arg2)));
+            }
+
+        private:
+            function_type fptr_;
+        };
+    } /*namespace pyutil*/
+}
+
+/** end pycaller.hpp **/

xo-pyutil/include/xo/pyutil/pyutil.hpp

@@ -0,0 +1,30 @@
+/* @file pyutil.hpp
+ *
+ * utility stuff to be used across multiple pybind11 .cpp files
+ */
+
+#pragma once
+
+#include "xo/refcnt/Refcounted.hpp"
+#include "xo/refcnt/Unowned.hpp"
+#include <pybind11/pybind11.h>
+
+/* xo::ref::intrusive_ptr<T> is an intrusively-reference-counted pointer.
+ * always safe to create one from a T* p
+ * (since refcount is directly accessible from p)
+ *
+ * Need declaration like this before any pybind11 bindings
+ * that expose an object of types like
+ * (a) intrusive_ptr<T> or
+ * (b) T * / T const * / T & / T const & to python.
+ * If this were not done,  pybind11 would by default use unique_ptr<intrusive_ptr<T>>
+ * (ok but inefficient) or unique_ptr<T> (fatal!)
+ */
+PYBIND11_DECLARE_HOLDER_TYPE(T, xo::ref::intrusive_ptr<T>, true);
+
+/* xo::ref::unowned_ptr<T> is an unmanaged pointer.
+ * use this for immortal objects that pybind11 must not delete.
+ */
+PYBIND11_DECLARE_HOLDER_TYPE(T, xo::ref::unowned_ptr<T>, true);
+
+/* end pyutil.hpp */