From 0e38aa7f372f9be4e89cc517839c85d63ab65fb6 Mon Sep 17 00:00:00 2001 From: Dave Abrahams Date: Mon, 30 Sep 2002 16:52:57 +0000 Subject: [PATCH] doc updates [SVN r15571] --- doc/v2/ObjectWrapper.html | 155 ++++++++++++++++++++++++++++++++++++++ doc/v2/args.html | 103 +++++++++++++++++++++++++ doc/v2/class.html | 33 ++++---- doc/v2/faq.html | 108 +++++++++++++++++--------- 4 files changed, 348 insertions(+), 51 deletions(-) create mode 100644 doc/v2/ObjectWrapper.html create mode 100644 doc/v2/args.html diff --git a/doc/v2/ObjectWrapper.html b/doc/v2/ObjectWrapper.html new file mode 100644 index 00000000..c7d555cd --- /dev/null +++ b/doc/v2/ObjectWrapper.html @@ -0,0 +1,155 @@ + + + + + + + + + Boost.Python - ObjectWrapper Concept + + + + + + + + + +
+

C++ Boost

+ 		+

Boost.Python

+ +

ObjectWrapper and TypeWrapper Concepts

+
+
+ +
+
Introduction
+ +
Concept Requirements
+ +
+
+
ObjectWrapper Concept
+ +
TypeWrapper Concept
+
+
+ +
Caveat
+
+ +

Introduction

+ +

This page defines two concepts used to describe classes which manage a + Python objects, and which are intended to support usage with a + Python-like syntax.

+ +

Concept Requirements

+ +

ObjectWrapper Concept

+ Models of the ObjectWrapper concept have object as a publicly-accessible base class, + and are used to supply special construction behavior and/or additional + convenient functionality through (often templated) member functions. + Except when the return type R is itself an TypeWrapper, a member function invocation of + the form +
+x.some_function(a1, a2,...an)
+
+ always has semantics equivalent to: +
+extract<R>(x.attr("some_function")(object(a1), object(a2),...object(an)))()
+
+ When the R is an TypeWrapper, the result type may be + constructed by taking direct posession of: +
+x.attr("some_function")(object(a1), object(a2),...object(an)).ptr()
+
+ [see caveat below] + +

TypeWrapper Concept

+ TypeWrapper is a refinement of ObjectWrapper which is associated with a + particular Python type X. For a given TypeWrapper + T, a valid constructor expression +
+T(a1, a2,...an)
+
+ builds a new T object managing the result of invoking + X with arguments corresponding to +
+object(a1), object(a2),...object(an)
+
+ +When used as arguments to wrapped C++ functions, or as the template +parameter to extract<>, only +instances of the associated Python type will be considered a match. + +

Caveat

+ The upshot of the special member function invocation rules when the + return type is a TypeWrapper is that it is possible for the returned + object to manage a Python object of an inappropriate type. This is not + usually a serious problem; the worst-case result is that errors will be + detected at runtime a little later than they might otherwise be. For an + example of how this can occur, note that the dict member function items + returns an object of type list. Now suppose the user defines this + dict subclass in Python: +
+>>> class mydict(dict):
+...     def items(self):
+...         return tuple(dict.items(self)) # return a tuple
+
+ Since an instance of mydict is also an instance of + dict, when used as an argument to a wrapped C++ function, + boost::python::dict can + accept objects of Python type mydict. Invoking + items() on this object can result in an instance of boost::python::list which actually + holds a Python tuple. Subsequent attempts to use list methods (e.g. + append, or any other mutating operation) on this object will + raise the same exception that would occur if you tried to do it from + Python. +
+ +

Revised + + 30 Sept, 2002 +

+ +

© Copyright Dave Abrahams 2002. All Rights + Reserved.

+ +

Permission to copy, use, modify, sell and distribute this software is + granted provided this copyright notice appears in all copies. This + software is provided "as is" without express or implied warranty, and + with no claim as to its suitability for any purpose.

+ + + diff --git a/doc/v2/args.html b/doc/v2/args.html new file mode 100644 index 00000000..93443091 --- /dev/null +++ b/doc/v2/args.html @@ -0,0 +1,103 @@ + + + + + + + + + Boost.Python - <boost/python/args.hpp> + + + + + + + + + +
+

C++ Boost

+ 		+

Boost.Python

+ +

Header <boost/python/args.hpp>

+
+
+ +

Contents

+ +
+
Introduction
+ +
keyword-expressions
+ +
Functions
+ +
+
+
args(...)
+
+
+ +
Example(s)
+
+
+ +

Introduction

+ +

Supplies a family of overloaded functions for specifying argument + keywords for wrapped C++ functions.

+ +

keyword-expressions

+ +

A keyword-expression results in an object which holds a + sequence of ntbses, and whose type + encodes the number of keywords specified.

+ +

Functions

+ +

args(...)

+
+unspecified1 args(char const*);
+unspecified2 args(char const*, char const*);
+   .
+   .
+   .
+unspecifiedN args(char const*, char const*, ... char const*);
+
+ +
+
Requires: Every argument must be a ntbs.
+ +
Returns: an object representing a keyword-expression encapsulating the + arguments passed.
+
+ +

Example

+
+#include <boost/python/def.hpp>
+using namespace boost::python;
+
+int f(int x, int y, int z);
+
+BOOST_PYTHON_MODULE_INIT(xxx)
+{
+   def("f", f, args("x", "y", "z"));
+}
+
+ +

Revised 05 November, 2001

+ +

© Copyright Dave Abrahams 2002. All Rights + Reserved.

+ + + diff --git a/doc/v2/class.html b/doc/v2/class.html index 240a1364..c66bf8dc 100644 --- a/doc/v2/class.html +++ b/doc/v2/class.html @@ -247,7 +247,7 @@ namespace boost { namespace python { template <class T - , class Bases = bases<> + , class Bases = bases<> , class HeldType = T , class NonCopyable = unspecified > @@ -742,23 +742,26 @@ template <class Policies> properties, used to describe a family of __init__ methods to be generated for an extension class: -
-
docstring: An ntbs whose - value will bound to the method's __doc__ attribute
+
+
+
docstring: An ntbs + whose value will bound to the method's __doc__ + attribute
-
keywords: A keyword-expression which will be - used to name (a trailing subset of) the arguments to the generated - __init__ function(s).
+
keywords: A keyword-expression which will be + used to name (a trailing subsequence of) the arguments to the generated + __init__ function(s).
-
call policies: An instance of a model of CallPolicies.
+
call policies: An instance of a model of CallPolicies.
-
argument types: An MPL sequence of C++ argument types which - will be used to construct the wrapped C++ object. An init expression - has one or more valid prefixes which are given by a sequence of - prefixes of its argument types.
-
+
argument types: An MPL sequence of C++ argument types + which will be used to construct the wrapped C++ object. An init + expression has one or more valid prefixes which are given by a + sequence of prefixes of its argument types.
+
+

Class template optional<T1 = unspecified, T2 = diff --git a/doc/v2/faq.html b/doc/v2/faq.html index 78a3940f..8e8be4e5 100644 --- a/doc/v2/faq.html +++ b/doc/v2/faq.html @@ -1,39 +1,75 @@ + + - - - -Boost.Python - FAQ - - - + + + + + Boost.Python - FAQ + + + +
- - - - -
-

-

- 		-

Boost.Python

-

Frequently Asked Questions (FAQs)

-
-
-
-
{{question}}
-
{{question}}
-
-

{{question}}

-

{{answer}}

-

{{question}}

-

{{answer}}

-
-

Revised - - 05 November, 2002 - -

-

© Copyright Dave Abrahams - 2002. All Rights Reserved.

- + + +

C++ Boost

+ + + +

Boost.Python

+ +

Frequently Asked Questions (FAQs)

+ + + +
+ +
+
{{question}}
+ +
{{question}}
+
+ +

Is return_internal reference efficient?

+ +
+ Q: I have an object composed of 12 doubles. A const& to this object is + returned by a member function of another class. From the viewpoint of + using the returned object in Python I do not care if I get a copy or a + reference to the returned object. In Boost.Python Version 2 I have the + choice of using copy_const_reference or return_internal_reference. Are + there considerations that would lead me to prefer one over the other, + such as size of generated code or memory overhead? + +

A: copy_const_reference will make an instance with storage for one of + your objects, size = base_size + 12 * sizeof(double). + return_internal_reference will make an instance with storage for a + pointer to one of your objects, size = base_size + sizeof(void*). + However, it will also create a weak reference object which goes in the + source object's weakreflist and a special callback object to manage the + lifetime of the internally-referenced object. My guess? + copy_const_reference is your friend here, resulting in less overall + memory use and less fragmentation, also probably fewer total cycles.

+
+ +

{{question}}

+ +

{{answer}}

+
+ +

Revised + + 05 November, 2002 + +

+ +

© Copyright Dave Abrahams 2002. All Rights + Reserved.

+ +