diff options
Diffstat (limited to 'libs/bind/doc/bind/faq.qbk')
-rw-r--r-- | libs/bind/doc/bind/faq.qbk | 99 |
1 files changed, 99 insertions, 0 deletions
diff --git a/libs/bind/doc/bind/faq.qbk b/libs/bind/doc/bind/faq.qbk new file mode 100644 index 000000000..8406a19f1 --- /dev/null +++ b/libs/bind/doc/bind/faq.qbk @@ -0,0 +1,99 @@ +[/ + / Copyright (c) 2001, 2002 Peter Dimov and Multi Media Ltd. + / Copyright (c) 2003-2008 Peter Dimov + / + / Distributed under the Boost Software License, Version 1.0. (See + / accompanying file LICENSE_1_0.txt or copy at + / http://www.boost.org/LICENSE_1_0.txt) + /] + +[section:faq Frequently Asked Questions] + +[section Why doesn't this compile?] + +See the dedicated [link bind.troubleshooting Troubleshooting section]. + +[endsect] + +[section Why does this compile? It should not.] + +Probably because you used the general `bind<R>(f, ...)` syntax, thereby +instructing `bind` to not "inspect" f to detect arity and return type errors. + +[endsect] + +[section:Q_forms What is the difference between `bind(f, ...)` and `bind<R>(f, ...)`?] + +The first form instructs `bind` to inspect the type of `f` in order to +determine its arity (number of arguments) and return type. Arity errors will +be detected at "bind time". This syntax, of course, places some requirements +on `f`. It must be a function, function pointer, member function pointer, or a +function object that defines a nested type named `result_type`; in short, it +must be something that `bind` can recognize. + +The second form instructs `bind` to not attempt to recognize the type of `f`. +It is generally used with function objects that do not, or cannot, expose +`result_type`, but it can also be used with nonstandard functions. For example, +the current implementation does not automatically recognize variable-argument +functions like `printf`, so you will have to use `bind<int>(printf, ...)`. +Note that an alternative `bind(type<R>(), f, ...)` syntax is supported for +portability reasons. + +Another important factor to consider is that compilers without partial +template specialization or function template partial ordering support cannot +handle the first form when `f` is a function object, and in most cases will +not handle the second form when `f` is a function (pointer) or a member +function pointer. + +[endsect] + +[section Does bind work with Windows API functions?] + +Yes, if you [link bind.implementation.stdcall `#define +BOOST_BIND_ENABLE_STDCALL`]. An alternative is to treat the function as a +[link bind.purpose.with_function_objects generic function object] and use the +`bind<R>(f, ...)` syntax. + +[endsect] + +[section Does bind work with COM methods?] + +Yes, if you [link bind.implementation.stdcall `#define +BOOST_MEM_FN_ENABLE_STDCALL`]. + +[endsect] + +[section Does bind work with Mac toolbox functions?] + +Yes, if you [link bind.implementation.stdcall `#define +BOOST_BIND_ENABLE_PASCAL`]. An alternative is to treat the function as a [link +bind.purpose.with_function_objects generic function object] and use the +`bind<R>(f, ...)` syntax. + +[endsect] + +[section Does bind work with extern "C" functions?] + +Sometimes. On some platforms, pointers to extern "C" functions are equivalent +to "ordinary" function pointers, so they work fine. Other platforms treat them +as different types. A platform-specific implementation of `bind` is expected +to handle the problem transparently; this implementation does not. As usual, +the workaround is to treat the function as a [link +bind.purpose.with_function_objects generic function object] and use the +`bind<R>(f, ...)` syntax. + +[endsect] + +[section Why doesn't bind automatically recognize nonstandard functions?] + +Non-portable extensions, in general, should default to off to prevent vendor +lock-in. Had the [link bind.implementation.stdcall appropriate macros] been +defined automatically, you could have accidentally taken advantage of them +without realizing that your code is, perhaps, no longer portable. In addition, +some compilers have the option to make `__stdcall` (`__fastcall`) their +default calling convention, in which case no separate support would be +necessary. + +[endsect] + +[endsect] |