add subtree-ish sources for 12.0.3

[ceph.git] / ceph / src / boost / libs / python / doc / reference / module.qbk

diff --git a/ceph/src/boost/libs/python/doc/reference/module.qbk b/ceph/src/boost/libs/python/doc/reference/module.qbk
new file mode 100644 (file)
index 0000000..31c9fec
--- /dev/null
+++ b/ceph/src/boost/libs/python/doc/reference/module.qbk
@@ -0,0 +1,41 @@
+[section boost/python/module.hpp]
+[section Introduction]
+This header provides the basic facilities needed to create a Boost.Python extension module. 
+[endsect]
+[section Macros]
+`BOOST_PYTHON_MODULE(name)` is used to declare Python [@http://www.python.org/doc/2.2/ext/methodTable.html#SECTION003400000000000000000 module initialization functions]. The name argument must exactly match the name of the module to be initialized, and must conform to Python's [@http://www.python.org/doc/2.2/ref/identifiers.html identifier naming rules]. Where you would normally write
+
+``
+extern "C" void initname()
+{
+   ...
+}
+``
+Boost.Python modules should be initialized with
+``
+BOOST_PYTHON_MODULE(name)
+{
+   ...
+}
+``
+This macro generates two functions in the scope where it is used: `extern "C" void initname()`, and `void init_module_name()`, whose body must follow the macro invocation. `init_name` passes `init_module_name` to [link high_level_components.boost_python_errors_hpp.functions handle_exception()] so that any C++ exceptions generated are safely processeed. During the body of `init_name`, the [link high_level_components.boost_python_scope_hpp current scope] refers to the module being initialized. 
+[endsect]
+[section Examples]
+C++ module definition:
+``
+#include <boost/python/module.hpp>
+
+BOOST_PYTHON_MODULE(xxx)
+{
+    throw "something bad happened"
+}
+``
+Interactive Python:
+``
+>>> import xxx
+Traceback (most recent call last):
+  File "", line 1, in ?
+RuntimeError: Unidentifiable C++ Exception
+``
+[endsect]
+[endsect]