include/MUtils/JobObject.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // MuldeR's Utilities for Qt
   3 // Copyright (C) 2004-2017 LoRd_MuldeR <MuldeR2@GMX.de>
   4 //
   5 // This library is free software; you can redistribute it and/or
   6 // modify it under the terms of the GNU Lesser General Public
   7 // License as published by the Free Software Foundation; either
   8 // version 2.1 of the License, or (at your option) any later version.
   9 //
  10 // This library is distributed in the hope that it will be useful,
  11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13 // Lesser General Public License for more details.
  14 //
  15 // You should have received a copy of the GNU Lesser General Public
  16 // License along with this library; if not, write to the Free Software
  17 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
  18 //
  19 // http://www.gnu.org/licenses/lgpl-2.1.txt
  20 //////////////////////////////////////////////////////////////////////////////////
  21
  22 /**
  23 * @file
  24 * @brief This file contains function for creating and managing job objects
  25 *
  26 * Each instance of MUtils::JobObject represents a job object. Call MUtils::JobObject::addProcessToJob() to add another sub-process to the job object. Call MUtils::JobObject::terminateJob() to terminate *all* sub-processes that currently belong to the job object at once.
  27 *
  28 * Note that all sub-processes that belong to the job object will be terminated when *this* process exits, gracefully or due to a crash. All sub-process belonging to a job object also are terminated when the corresponding MUtils::JobObject instance is destroyed.
  29 */
  30
  31 #pragma once
  32
  33 #include <MUtils/Global.h>
  34
  35 class QProcess;
  36
  37 namespace MUtils
  38 {
  39         /**
  40         * @brief This class represents a job object
  41         *
  42         * Call addProcessToJob() to add another sub-process to this job object. Call terminateJob() to terminate all sub-processes that belong to this job object. Note that all sub-processes that belong to this job object will also be terminated when *this* process exits, gracefully or due to a crash.
  43         *
  44         * Also, when the JobObject instance is destroyed, all sub-process that belong to its corresponding job object and that are still running will be terminated!
  45         */
  46         class MUTILS_API JobObject
  47         {
  48         public:
  49                 /**
  50                 * \brief Create a new JobObject instance
  51                 *
  52                 * Creating a new JobObject instance automatically creates a new job object on the system-level. Check isObjectCreated() to test whether the job object was successfully created or not.
  53                 */
  54                 JobObject(void);
  55
  56                 /**
  57                 * \brief Destroys the JobObject instance
  58                 *
  59                 * If the job object still has any running sub-processes left when the corresponding JobObject instance is destroyed, these sub-process are terminated!
  60                 */
  61                 ~JobObject(void);
  62
  63                 /**
  64                 * \brief Test whether job object was created successfully
  65                 *
  66                 * The job object will be created automatically when a new JobObject instance is created. However, the constructor has **no** to tell whether the job object was created successfully on the system-level. Call this function to test whether the job object has been created.
  67                 *
  68                 * \return The function returns `true`, if and only if a job object was successfully created; otherwise it returns `false`.
  69                 */
  70                 bool isObjectCreated(void);
  71
  72                 /**
  73                 * \brief Add a process to the job object
  74                 *
  75                 * This function adds a another sub-process to the job object that is represented by this JobObject instance. Job object limitations apply to the sub-process a
  76                 *
  77                 * \param process A read-only pointer to the [QProcess](http://doc.qt.io/qt-4.8/qprocess.html) object that represents the sub-process to be added to the job object. The sub-process must be in the "running" state; otherwise the function will fail.
  78                 *
  79                 * \return The function returns `true`, if and only if the process was successfully added to the job object; otherwise it returns `false`.
  80                 */
  81                 bool addProcessToJob(const QProcess *const process);
  82
  83                 /**
  84                 * \brief Terminate all sub-processes of the job object
  85                 *
  86                 * This function immediately terminates *all* running sub-processes that belong to the job object represented by this JobObject instance at once.
  87                 *
  88                 * \param exitCode The exit code to be set for the sub-process when they are terminated.
  89                 *
  90                 * \return The function returns `true`, if the sub-processes were destroyed successfully, even if there were no running sub-process left; otherwise it returns `false`.
  91                 */
  92                 bool terminateJob(const quint32 &exitCode);
  93
  94         private:
  95                 uintptr_t m_jobPtr;
  96                 MUTILS_NO_COPY(JobObject)
  97         };
  98 }