[ceph.git] / ceph / src / civetweb / src / third_party / duktape-1.8.0 / examples / cpp-exceptions / README.rst

=========================================
C++ exceptions for long control transfers
=========================================

Normally Duktape uses ``setjmp()`` / ``longjmp()`` or their variants for
internal long control transfers.  One downside of these functions is that
C++ automatic destructors (scope-based resource management, SBRM, a special
case of RAII) in Duktape/C functions won't be executed which is awkward for
C++ programmers.

When ``DUK_USE_CPP_EXCEPTIONS`` (``DUK_OPT_CPP_EXCEPTIONS``) is defined, and
both Duktape and application code is compiled using a C++ compiler, Duktape
uses C++ ``try-catch`` and ``throw`` for internal long control transfers.
This allows automatic destructors to run as expected.  The config option is
not enabled by default because C++ exceptions are sometimes disabled even
when a C++ compiler is used (e.g. for performance reasons).

The ``cpp_exceptions.cpp`` example illustrates how C++ exceptions can be
used in Duktape/C functions at the moment:

* Duktape uses C++ try/catch/throw internally; this is not visible to user
  code directly.

* Automatic destructors (scope-based resource management) work as expected.

* C++ exceptions can be used in Duktape/C functions normally, but user
  exceptions must be caught before they reach Duktape.  If this is not
  done, such exceptions are caught by Duktape and converted to API errors
  (in other words, they won't propagate "through" Duktape at the moment).
Commit	Line	Data
11fdf7f2 TL	1	=========================================
	2	C++ exceptions for long control transfers
	3	=========================================
	4
	5	Normally Duktape uses ``setjmp()`` / ``longjmp()`` or their variants for
	6	internal long control transfers. One downside of these functions is that
	7	C++ automatic destructors (scope-based resource management, SBRM, a special
	8	case of RAII) in Duktape/C functions won't be executed which is awkward for
	9	C++ programmers.
	10
	11	When ``DUK_USE_CPP_EXCEPTIONS`` (``DUK_OPT_CPP_EXCEPTIONS``) is defined, and
	12	both Duktape and application code is compiled using a C++ compiler, Duktape
	13	uses C++ ``try-catch`` and ``throw`` for internal long control transfers.
	14	This allows automatic destructors to run as expected. The config option is
	15	not enabled by default because C++ exceptions are sometimes disabled even
	16	when a C++ compiler is used (e.g. for performance reasons).
	17
	18	The ``cpp_exceptions.cpp`` example illustrates how C++ exceptions can be
	19	used in Duktape/C functions at the moment:
	20
	21	* Duktape uses C++ try/catch/throw internally; this is not visible to user
	22	code directly.
	23
	24	* Automatic destructors (scope-based resource management) work as expected.
	25
	26	* C++ exceptions can be used in Duktape/C functions normally, but user
	27	exceptions must be caught before they reach Duktape. If this is not
	28	done, such exceptions are caught by Duktape and converted to API errors
	29	(in other words, they won't propagate "through" Duktape at the moment).