executor.hpp

Go to the documentation of this file.

// Copyright (c) 2006, 2007 Julio M. Merino Vidal
// Copyright (c) 2008 Ilya Sokolov, Boris Schaeling
// Copyright (c) 2009 Boris Schaeling
// Copyright (c) 2010 Felipe Tanus, Boris Schaeling
// Copyright (c) 2011, 2012 Jeff Flinn, Boris Schaeling
//
// 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)
 
/**
 * \file boost/process/executor.hpp
 *
 * Defines an executor which can create child processes.
 */
 
#pragma once
 
#include <boost/process/config.hpp>
 
#include BOOST_PROCESS_PLATFORM_PROMOTE_PATH(executor)
BOOST_PROCESS_PLATFORM_PROMOTE_NAMESPACE(executor)
 
#if defined(BOOST_PROCESS_DOXYGEN)
namespace boost
{
    namespace process
    {
 
        /**
         * Starts a program.
         *
         * boost::process::executor is a functor which calls the system functions
         * to start a program. Before system functions are called it iterates
         * over initializers and calls a member function passing a reference
         * to itself as a parameter. Initializers get then a chance to setup
         * the executor. If system functions fail boost::process::executor again
         * iterates over initializers and calls another member function passing a
         * reference to itself as a parameter. This gives initializers a
         * chance to handle the error.
         *
         * \note Library users shouldn't need to use boost::process::executor.
         *       It is recommended to call boost::process::execute which uses
         *       boost::pocess::executor internally.
         */
        struct executor
        {
            /**
             * Default constructor.
             */
            executor();
 
            /**
             * Starts a program.
             *
             * \tparam initializers define what and how the program is started
             */
            template <class Initializer, class... Initializers>
            child operator()(const Initializer& initializer, const Initializers... &initializers);
 
            ///\defgroup WindowsOnly Windows only.
            ///@{
 
            /**
             * Program name.
             *
             * \remark <em>Windows only.</em>
             */
            LPCTSTR exe;
 
            /**
             * Command line.
             *
             * \remark <em>Windows only.</em>
             */
            LPTSTR cmd_line;
 
            /**
             * Process attributes.
             *
             * \remark <em>Windows only.</em>
             */
            LPSECURITY_ATTRIBUTES proc_attrs;
 
            /**
             * Thread attributes.
             *
             * \remark <em>Windows only.</em>
             */
            LPSECURITY_ATTRIBUTES thread_attrs;
 
            /**
             * Flag to inherit handles.
             *
             * \remark <em>Windows only.</em>
             */
            BOOL inherit_handles;
 
            /**
             * Creation flags.
             *
             * \remark <em>Windows only.</em>
             */
            DWORD creation_flags;
 
            /**
             * Environment variables.
             *
             * \remark <em>Windows only.</em>
             */
            LPVOID env;
 
            /**
             * Work directory.
             *
             * \remark <em>Windows only.</em>
             */
            LPCTSTR work_dir;
 
            /**
             * Startupinfo structure.
             *
             * \remark <em>Windows only.</em>
             */
            STARTUPINFO startup_info;
 
            /**
             * Startupinfoex structure.
             *
             * If this member variable is available, \c startup_info is a reference
             * to \c StartupInfo in STARTUPINFOEX.
             *
             * \remark <em>Windows Vista, Windows Server 2008 or better.</em>
             */
            STARTUPINFOEX startup_info_ex;
 
            /**
             * Process information.
             *
             * \c proc_info contains the result after a child process
             * could be started successfully.
             *
             * \remark <em>Windows only.</em>
             */
            PROCESS_INFORMATION proc_info;
 
            ///@}
 
            ///\defgroup POSIXOnly POSIX only.
            ///@{
 
            /**
             * Program name.
             *
             * \remark <em>POSIX only.</em>
             */
            const char* exe;
 
            /**
             * Command line arguments.
             *
             * \remark <em>POSIX only.</em>
             */
            char** cmd_line;
 
            /**
             * Environment variables.
             *
             * \remark <em>POSIX only.</em>
             */
            char** env;
 
            ///@}
        };
 
    }
}
#endif