CGAL 5.5 - Manual
General Information

The chapter explains some basic features of CGAL such as thread safety, code deprecation, checking of pre- and postconditions and altering the failure behavior, and how to control inlining.

These concepts are further developed in the Developer Manual.

Namespace CGAL

All names introduced by CGAL, especially those documented in these manuals, are in a namespace called CGAL, which is in global scope. A user can either qualify names from CGAL by adding CGAL::, e.g., CGAL::Point_2< CGAL::Exact_predicates_inexact_constructions_kernel >, make a single name from CGAL visible in a scope via a using statement, e.g., using CGAL::Point_2;, and then use this name unqualified in this scope, or even make all names from namespace CGAL visible in a scope with using namespace CGAL;. The latter, however, is likely to give raise to name conflicts and is therefore not recommended.

Thread Safety

CGAL is progressively being made thread-safe. The guidelines which are followed are:

  • it should be possible to use different objects in different threads at the same time (of the same type or not),
  • it is not safe to access the same object from different threads at the same time, unless otherwise specified in the class documentation.

If the macro CGAL_HAS_THREADS is not defined, then CGAL assumes it can use any thread-unsafe code (such as static variables). By default, this macro is not defined, unless BOOST_HAS_THREADS or _OPENMP is defined. It is possible to force its definition in the compiler options, and it is possible to prevent its default definition by defining the macro CGAL_HAS_NO_THREADS. If you are using CMake, then you can set the CMake option CGAL_HAS_NO_THREADS to TRUE. In addition to defining the preprocessor macro CGAL_HAS_NO_THREADS`, it will also avoid CMake to link with the native threads support library on your system.

C++14 Support

After being based on the C++ standard released in 1998 (and later refined in 2003) for a long time, CGAL is now based on a newer major version of the standard, C++14.

Functor Return Types

CGAL functors support the result_of protocol. If a functor F has the same return type across all overloads of operator(), the nested type F::result_type is defined to be that type. Otherwise the return type of calling the functor with an argument of type Arg can be accessed through CGAL::cpp11::result_of<F(Arg)>::type .

Checks

Much of the CGAL code contains assert statements for preconditions, and postconditions of functions as well as in the code. These assertions can be switched on and off per package and the user can change the error behaviour. For details see Section Checks of Chapter Chapter_STL_Extensions_for_CGAL.

Compile-time Flags to Control Inlining

Making functions inlined can, at times, improve the efficiency of your code. However this is not always the case and it can differ for a single function depending on the application in which it is used. Thus CGAL defines a set of compile-time macros that can be used to control whether certain functions are designated as inlined functions or not. The following table lists the macros and their default values, which are set in one of the CGAL include files.

Macro Name Default
CGAL_KERNEL_INLINE inline
CGAL_KERNEL_MEDIUM_INLINE
CGAL_KERNEL_LARGE_INLINE
CGAL_MEDIUM_INLINE inline
CGAL_LARGE_INLINE
CGAL_HUGE_INLINE

If you wish to change the value of one or more of these macros, you can simply give it a new value when compiling. For example, to make functions that use the macro CGAL_KERNEL_MEDIUM_INLINE inline functions, you should set the value of this macro to inline instead of the default blank.

Note that setting inline manually is very fragile, especially in a template context. It is usually better to let the compiler select by himself which functions should be inlined or not.

Identifying the Version of CGAL

Every release of CGAL defines the following preprocessor macros:

CGAL_VERSION_STR
a textual description of the current release (e.g., or 3.3 or 3.2.1 or 3.2.1-I-15) as a string literal
CGAL_VERSION_NR

a numerical description of the current release such that more recent releases have higher number.

More precisely, it is defined as 1MMmmbiiii, where MM is the major release number (e.g. 03), mm is the minor release number (e.g. 02), b is the bug-fix release number (e.g. 0), and iiii is the internal release number (e.g. 0001). For public releases, the latter is defined as 1000. Examples: for the public release 3.2.4 this number is 1030241000; for internal release 3.2-I-1, it is 1030200001. Note that this scheme was modified around 3.2-I-30.

CGAL_VERSION_NUMBER(M,m,b)
a function macro computing the version number macro from the M.m.b release version. Note that the internal release number is dropped here. Example: CGAL_VERSION_NUMBER(3,2,4) is equal to 1030241000.

The macro CGAL_VERSION is deprecated. It is the same as CGAL_VERSION_STR, but not as a string literal.

CGAL 5.5 - Manual
General Information

The chapter explains some basic features of CGAL such as thread safety, code deprecation, checking of pre- and postconditions and altering the failure behavior, and how to control inlining.

These concepts are further developed in the Developer Manual.

Namespace CGAL

All names introduced by CGAL, especially those documented in these manuals, are in a namespace called CGAL, which is in global scope. A user can either qualify names from CGAL by adding CGAL::, e.g., CGAL::Point_2< CGAL::Exact_predicates_inexact_constructions_kernel >, make a single name from CGAL visible in a scope via a using statement, e.g., using CGAL::Point_2;, and then use this name unqualified in this scope, or even make all names from namespace CGAL visible in a scope with using namespace CGAL;. The latter, however, is likely to give raise to name conflicts and is therefore not recommended.

Thread Safety

CGAL is progressively being made thread-safe. The guidelines which are followed are:

  • it should be possible to use different objects in different threads at the same time (of the same type or not),
  • it is not safe to access the same object from different threads at the same time, unless otherwise specified in the class documentation.

If the macro CGAL_HAS_THREADS is not defined, then CGAL assumes it can use any thread-unsafe code (such as static variables). By default, this macro is not defined, unless BOOST_HAS_THREADS or _OPENMP is defined. It is possible to force its definition in the compiler options, and it is possible to prevent its default definition by defining the macro CGAL_HAS_NO_THREADS. If you are using CMake, then you can set the CMake option CGAL_HAS_NO_THREADS to TRUE. In addition to defining the preprocessor macro CGAL_HAS_NO_THREADS`, it will also avoid CMake to link with the native threads support library on your system.

C++14 Support

After being based on the C++ standard released in 1998 (and later refined in 2003) for a long time, CGAL is now based on a newer major version of the standard, C++14.

Functor Return Types

CGAL functors support the result_of protocol. If a functor F has the same return type across all overloads of operator(), the nested type F::result_type is defined to be that type. Otherwise the return type of calling the functor with an argument of type Arg can be accessed through CGAL::cpp11::result_of<F(Arg)>::type .

Checks

Much of the CGAL code contains assert statements for preconditions, and postconditions of functions as well as in the code. These assertions can be switched on and off per package and the user can change the error behaviour. For details see Section Checks of Chapter Chapter_STL_Extensions_for_CGAL.

Compile-time Flags to Control Inlining

Making functions inlined can, at times, improve the efficiency of your code. However this is not always the case and it can differ for a single function depending on the application in which it is used. Thus CGAL defines a set of compile-time macros that can be used to control whether certain functions are designated as inlined functions or not. The following table lists the macros and their default values, which are set in one of the CGAL include files.

Macro Name Default
CGAL_KERNEL_INLINE inline
CGAL_KERNEL_MEDIUM_INLINE
CGAL_KERNEL_LARGE_INLINE
CGAL_MEDIUM_INLINE inline
CGAL_LARGE_INLINE
CGAL_HUGE_INLINE

If you wish to change the value of one or more of these macros, you can simply give it a new value when compiling. For example, to make functions that use the macro CGAL_KERNEL_MEDIUM_INLINE inline functions, you should set the value of this macro to inline instead of the default blank.

Note that setting inline manually is very fragile, especially in a template context. It is usually better to let the compiler select by himself which functions should be inlined or not.

Identifying the Version of CGAL

Every release of CGAL defines the following preprocessor macros:

CGAL_VERSION_STR
a textual description of the current release (e.g., or 3.3 or 3.2.1 or 3.2.1-I-15) as a string literal
CGAL_VERSION_NR

a numerical description of the current release such that more recent releases have higher number.

More precisely, it is defined as 1MMmmbiiii, where MM is the major release number (e.g. 03), mm is the minor release number (e.g. 02), b is the bug-fix release number (e.g. 0), and iiii is the internal release number (e.g. 0001). For public releases, the latter is defined as 1000. Examples: for the public release 3.2.4 this number is 1030241000; for internal release 3.2-I-1, it is 1030200001. Note that this scheme was modified around 3.2-I-30.

CGAL_VERSION_NUMBER(M,m,b)
a function macro computing the version number macro from the M.m.b release version. Note that the internal release number is dropped here. Example: CGAL_VERSION_NUMBER(3,2,4) is equal to 1030241000.

The macro CGAL_VERSION is deprecated. It is the same as CGAL_VERSION_STR, but not as a string literal.