Merge pull request #205 from bluescarni/pr/fork_island

Fork island

CMakeLists.txt

@@ -48,6 +48,25 @@ if(PAGMO_BUILD_PAGMO)
 
     # Build option: enable Ipopt.
     option(PAGMO_WITH_IPOPT "Enable wrappers for the Ipopt solver." OFF)
+
+    # Detect if we can enable the fork_island UDI.
+    include(CheckIncludeFileCXX)
+    include(CheckCXXSymbolExists)
+    include(CMakePushCheckState)
+    CHECK_INCLUDE_FILE_CXX("sys/types.h" PAGMO_HAVE_SYS_TYPES_H)
+    CHECK_INCLUDE_FILE_CXX("unistd.h" PAGMO_HAVE_UNISTD_H)
+    cmake_push_check_state(RESET)
+    set(CMAKE_REQUIRED_DEFINITIONS -D_POSIX_C_SOURCE=1)
+    CHECK_CXX_SYMBOL_EXISTS(fork "unistd.h;sys/types.h" PAGMO_HAVE_FORK_SYSCALL)
+    cmake_pop_check_state()
+    if(PAGMO_HAVE_SYS_TYPES_H AND PAGMO_HAVE_UNISTD_H AND PAGMO_HAVE_FORK_SYSCALL)
+        message(STATUS "The fork_island UDI will be available.")
+        set(PAGMO_WITH_FORK_ISLAND YES)
+        set(PAGMO_ENABLE_FORK_ISLAND "#define PAGMO_WITH_FORK_ISLAND")
+    else()
+        message(STATUS "The fork_island UDI will NOT be available.")
+        set(PAGMO_WITH_FORK_ISLAND NO)
+    endif()
 else()
     # Initial setup of a pygmo build.
     project(pygmo VERSION ${PAGMO_PROJECT_VERSION} LANGUAGES CXX C)

config.hpp.in

@@ -37,6 +37,13 @@ see https://www.gnu.org/licenses/. */
 @PAGMO_ENABLE_EIGEN3@
 @PAGMO_ENABLE_NLOPT@
 @PAGMO_ENABLE_IPOPT@
+// NOTE: in order to enable the fork island, we have to:
+// - verify in the build system that the required headers and the fork() function
+//   are present (which will set the PAGMO_ENABLE_FORK_ISLAND variable), and
+// - verify that the _POSIX_C_SOURCE definition is active during compilation.
+#if defined(_POSIX_C_SOURCE)
+@PAGMO_ENABLE_FORK_ISLAND@
+#endif
 // clang-format on
 // End of defines instantiated by CMake.
 

doc/sphinx/changelog.rst

@@ -9,6 +9,8 @@ New
 
 - Implement the UDI extraction functionality for :cpp:class:`~pagmo::island` (`#207 <https://github.com/esa/pagmo2/pull/207>`__).
 
+- Implement the :cpp:class:`~pagmo::fork_island` UDI (`#205 <https://github.com/esa/pagmo2/pull/205>`__).
+
 - pip pygmo package for Python 3.7 (Linux) (`#196 <https://github.com/esa/pagmo2/pull/196>`__).
 
 - Implement the :class:`~pygmo.decorator_problem` Python meta-problem (`#195 <https://github.com/esa/pagmo2/pull/195>`__).
@@ -28,13 +30,15 @@ Changes
 Fix
 ~~~
 
+- Fix a missing ``inline`` specifier (`#206 <https://github.com/esa/pagmo2/pull/206>`__).
+
 - Fix a bunch of missing includes in ``pagmo.hpp`` (`#202 <https://github.com/esa/pagmo2/pull/202>`__).
 
 - Fixes for compiler warnings in GCC 8 (`#197 <https://github.com/esa/pagmo2/pull/197>`__).
 
-- Various documentation and CI fixes and enhancements (`#195 <https://github.com/esa/pagmo2/pull/195>`__,
+- Various documentation, build system and CI fixes and enhancements (`#195 <https://github.com/esa/pagmo2/pull/195>`__,
   `#196 <https://github.com/esa/pagmo2/pull/196>`__, `#204 <https://github.com/esa/pagmo2/pull/204>`__,
-  `#207 <https://github.com/esa/pagmo2/pull/207>`__).
+  `#205 <https://github.com/esa/pagmo2/pull/205>`__, `#207 <https://github.com/esa/pagmo2/pull/207>`__).
 
 2.8 (2018-07-12)
 ----------------

doc/sphinx/docs/cpp/cpp_docs.rst

@@ -78,6 +78,7 @@ Implemented islands
   :maxdepth: 1
 
   islands/thread_island
+  islands/fork_island
 
 Utilities
 ^^^^^^^^^

doc/sphinx/docs/cpp/islands/fork_island.rst

@@ -0,0 +1,95 @@
+Fork island
+===========
+
+.. versionadded:: 2.9
+
+*#include <pagmo/islands/fork_island.hpp>*
+
+.. note::
+
+   The :cpp:class:`~pagmo::fork_island` class is available only on POSIX platforms (e.g., Linux, OSX,
+   the BSDs, but *not* Microsoft Windows, unless some POSIX compatibility layer has been installed
+   on the system).
+
+.. cpp:namespace-push:: pagmo
+
+.. cpp:class:: fork_island
+
+   This user-defined island (UDI) will use the POSIX ``fork()`` system call to offload the evolution
+   of a population to a child process.
+
+   Generally speaking, users are encouraged to use :cpp:class:`~pagmo::thread_island` rather than
+   :cpp:class:`~pagmo::fork_island`: :cpp:class:`~pagmo::thread_island` performs better,
+   it works also with problems and algorithms which are not serialisable, and it is available on all
+   platforms.
+
+   :cpp:class:`~pagmo::fork_island` should however be preferred when dealing with problems and algorithms
+   which do not offer the basic :cpp:type:`~pagmo::thread_safety` guarantee. By offloading the optimisation
+   to a separate process (rather than a separate thread), :cpp:class:`~pagmo::fork_island` can ensure
+   that thread-unsafe problems and algorithms are always run in only one thread at a time.
+   This capability is particularly useful when wrapping in pagmo third-party code which does not support execution
+   in multithreaded contexts (a notable example is the :cpp:class:`~pagmo::ipopt` algorithm,
+   which uses the thread-unsafe IPOPT optimiser).
+
+   :cpp:class:`~pagmo::fork_island` is the UDI type automatically selected by the constructors of :cpp:class:`~pagmo::island`
+   on POSIX platforms when the island's problem and/or algorithm do not provide the basic :cpp:type:`~pagmo::thread_safety`
+   guarantee.
+
+   .. note::
+
+      :cpp:class:`~pagmo::fork_island` is not exposed in the Python bindings. Instead, pygmo provides a
+      :py:class:`process-based island <pygmo.mp_island>` via Python's :py:mod:`multiprocessing` module.
+
+   .. note::
+
+      When using memory checking tools such as valgrind, or the address/memory sanitizers from GCC/clang, be aware
+      that memory leaks in the child process may be flagged by such tools. These are spurious warnings due to the
+      fact that the child process is exited via ``std::exit()`` (which does not invoke the destructors
+      of objects with automatic storage duration). Thus, such warnings can be safely ignored.
+
+   .. cpp:function:: fork_island()
+   .. cpp:function:: fork_island(const fork_island &)
+   .. cpp:function:: fork_island(fork_island &&) noexcept
+
+      :cpp:class:`~pagmo::fork_island` is default, copy and move-constructible.
+
+   .. cpp:function:: void run_evolve(island &isl) const
+
+      This method will fork the calling process, and, in the child process, the :cpp:class:`~pagmo::population` of *isl* will be
+      evolved using the :cpp:class:`~pagmo::algorithm` of *isl*. At the end of the evolution, the evolved population and the
+      algorithm used for the evolution will be sent back to the parent process, where they will replace, in *isl*, the original
+      population and algorithm. The child process will then terminate via ``std::exit(0)``.
+
+      If any exception is raised during the evolution, the error message from the exception will be transferred back to the parent
+      process, where a ``std::runtime_error`` containing the error message from the child will be raised.
+
+      :param isl: the :cpp:class:`~pagmo::island` that will be evolved.
+
+      :exception std\:\:runtime_error: if any error arises from the use of POSIX primitives (``fork()``, pipes, etc.), or if any
+         error is generated in the child process.
+      :exception unspecified: any exception raised by:
+
+         - the serialisation of :cpp:class:`~pagmo::population` or :cpp:class:`~pagmo::algorithm`,
+         - :cpp:func:`pagmo::island::set_population()` or :cpp:func:`pagmo::island::set_algorithm()`.
+
+   .. cpp:function:: std::string get_name() const
+
+      :return: the string ``"Fork island"``.
+
+   .. cpp:function:: std::string get_extra_info() const
+
+      :return: if an evolution is ongoing, this method will return a string
+         representation of the ID of the child process. Otherwise, the ``"No active child."`` string will be returned.
+
+   .. cpp:function:: pid_t get_child_pid() const
+
+      :return: a signed integral value representing the process ID of the child process, if an evolution is ongoing. Otherwise,
+         ``0`` will be returned.
+
+   .. cpp:function:: template <typename Archive> void serialize(Archive &)
+
+      Serialisation support.
+
+      Note that :cpp:class:`~pagmo::fork_island` is stateless, and thus this (de)serialisation function is empty and performs no work.
+
+.. cpp:namespace-pop::

doc/sphinx/docs/cpp/islands/thread_island.rst

@@ -1,5 +1,7 @@
 Thread island
 =============
 
+*#include <pagmo/islands/thread_island.hpp>*
+
 .. doxygenclass:: pagmo::thread_island
    :members:

doc/sphinx/docs/island_list.rst

@@ -10,7 +10,8 @@ interface to acces their parallelization functionalities.
 ========================================================== ========================================= =========================================
 Common Name                                                Docs of the C++ class                     Docs of the python class                 
 ========================================================== ========================================= =========================================
-Thread Island                                              :cpp:class:`pagmo::thread_island`         :class:`pygmo.thread_island`                    
-Multiprocessing Island                                     N/A                                       :class:`pygmo.mp_island`                  
-Ipyparallel island                                         N/A                                       :class:`pygmo.ipyparallel_island`       
+Thread island                                              :cpp:class:`pagmo::thread_island`         :class:`pygmo.thread_island`
+Fork island                                                :cpp:class:`pagmo::fork_island`           N/A
+Multiprocessing island                                     N/A                                       :class:`pygmo.mp_island`
+Ipyparallel island                                         N/A                                       :class:`pygmo.ipyparallel_island`
 ========================================================== ========================================= =========================================

doc/sphinx/docs/python/tutorials/using_island.rst

@@ -16,7 +16,7 @@ coded in UDIs provided with pygmo, a list of which can be found at :ref:`islands
 
 .. note::
    A collection of :class:`pygmo.island` form an :class:`~pygmo.archipelago`, you can skip this tutorial and follow directly the tutorial ":ref:`py_tutorial_using_archipelago`"
-   in case you are happy with the defualt choices pygmo will do for you to parallelize your tasks via the :class:`~pygmo.archipelago`.
+   in case you are happy with the default choices pygmo will do for you to parallelize your tasks via the :class:`~pygmo.archipelago`.
 
 We start by instantiating an island.
 

include/pagmo/algorithms/cmaes.hpp

@@ -33,14 +33,14 @@ see https://www.gnu.org/licenses/. */
 
 #if defined(PAGMO_WITH_EIGEN3)
 
-#include <Eigen/Dense>
 #include <iomanip>
 #include <random>
 #include <string>
 #include <tuple>
 
 #include <pagmo/algorithm.hpp>
 #include <pagmo/detail/custom_comparisons.hpp>
+#include <pagmo/detail/eigen.hpp>
 #include <pagmo/exceptions.hpp>
 #include <pagmo/io.hpp>
 #include <pagmo/population.hpp>

include/pagmo/algorithms/nlopt.hpp

@@ -725,7 +725,7 @@ inline void nlopt_eq_c_wrapper(unsigned m, double *result, unsigned dim, const d
  *
  * .. seealso::
  *
- *    The `NLopt website <http://nlopt.readthedocs.io/en/latest/NLopt_Algorithms/>`__ contains a detailed description
+ *    The `NLopt website <https://nlopt.readthedocs.io/en/latest/NLopt_Algorithms/>`__ contains a detailed description
  *    of each supported solver.
  *
  * \endverbatim
@@ -805,7 +805,7 @@ class nlopt : public not_population_based
      * \verbatim embed:rst:leading-asterisk
      * .. seealso::
      *
-     *    The `NLopt website <http://nlopt.readthedocs.io/en/latest/NLopt_Algorithms/>`__ contains a detailed
+     *    The `NLopt website <https://nlopt.readthedocs.io/en/latest/NLopt_Algorithms/>`__ contains a detailed
      *    description of each supported solver.
      *
      * \endverbatim

include/pagmo/algorithms/pso.hpp

@@ -167,7 +167,7 @@ class pso
      * @param memory when true the particle velocities are not reset between successive calls to evolve
      * @param seed seed used by the internal random number generator (default is random)
      *
-     * @throws std::invalid_argument if omega is not in the [0,1] interval, eta1, eta2 are not in the [0,1] interval,
+     * @throws std::invalid_argument if omega is not in the [0,1] interval, eta1, eta2 are not in the [0,4] interval,
      * vcoeff is not in ]0,1], variant is not one of 1 .. 6, neighb_type is not one of 1 .. 4, neighb_param is zero
      */
     pso(unsigned int gen = 1u, double omega = 0.7298, double eta1 = 2.05, double eta2 = 2.05, double max_vel = 0.5,

include/pagmo/algorithms/xnes.hpp

@@ -33,16 +33,14 @@ see https://www.gnu.org/licenses/. */
 
 #if defined(PAGMO_WITH_EIGEN3)
 
-#include <Eigen/Dense>
-#include <unsupported/Eigen/MatrixFunctions>
-
 #include <iomanip>
 #include <random>
 #include <string>
 #include <tuple>
 
 #include <pagmo/algorithm.hpp>
 #include <pagmo/detail/custom_comparisons.hpp>
+#include <pagmo/detail/eigen.hpp>
 #include <pagmo/exceptions.hpp>
 #include <pagmo/io.hpp>
 #include <pagmo/population.hpp>

include/pagmo/detail/eigen.hpp

@@ -0,0 +1,48 @@
+/* Copyright 2017-2018 PaGMO development team
+
+This file is part of the PaGMO library.
+
+The PaGMO library is free software; you can redistribute it and/or modify
+it under the terms of either:
+
+  * the GNU Lesser General Public License as published by the Free
+    Software Foundation; either version 3 of the License, or (at your
+    option) any later version.
+
+or
+
+  * the GNU General Public License as published by the Free Software
+    Foundation; either version 3 of the License, or (at your option) any
+    later version.
+
+or both in parallel, as here.
+
+The PaGMO library is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+for more details.
+
+You should have received copies of the GNU General Public License and the
+GNU Lesser General Public License along with the PaGMO library.  If not,
+see https://www.gnu.org/licenses/. */
+
+#ifndef PAGMO_DETAIL_EIGEN_HPP
+#define PAGMO_DETAIL_EIGEN_HPP
+
+// NOTE: we have experimental evidence that on some platform/compiler combinations
+// Eigen is failing to include necessary header files. As a workaround, we use this header
+// to wrap any Eigen functionality that might be needed in pagmo, and we pre-emptively
+// include the missing headers as necessary.
+#if defined(__apple_build_version__)
+
+// NOTE: on OSX and if the _POSIX_C_SOURCE definition is active (or at least for some specific
+// values of this definition), Eigen uses the alloca() function without including the header
+// that declares it.
+#include <alloca.h>
+
+#endif
+
+#include <Eigen/Dense>
+#include <unsupported/Eigen/MatrixFunctions>
+
+#endif