E-MailRelay
gtask.h
Go to the documentation of this file.
1 //
2 // Copyright (C) 2001-2018 Graeme Walker <graeme_walker@users.sourceforge.net>
3 //
4 // This program is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
8 //
9 // This program is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 // GNU General Public License for more details.
13 //
14 // You should have received a copy of the GNU General Public License
15 // along with this program. If not, see <http://www.gnu.org/licenses/>.
16 // ===
17 ///
18 /// \file gtask.h
19 ///
20 
21 #ifndef G_NET_TASK__H
22 #define G_NET_TASK__H
23 
24 #include "gdef.h"
25 #include "geventhandler.h"
26 #include "gexception.h"
27 #include "gidentity.h"
28 #include "gexecutablecommand.h"
29 #include <memory>
30 
31 namespace GNet
32 {
33  class Task ;
34  class TaskImp ;
35  class TaskCallback ;
36 }
37 
38 /// \class GNet::Task
39 /// A class for running an exectuable in a separate process with an asychronous
40 /// completion callback.
41 ///
43 {
44 public:
45  G_EXCEPTION( Busy , "cannot execute command-line task: still busy from last time" ) ;
46  G_EXCEPTION( Error , "asynchronous task error" ) ;
47  G_EXCEPTION( Failed , "failed to collect task exit status" ) ;
48 
50  const std::string & exec_error_format = std::string() ,
51  const G::Identity & = G::Identity::invalid() ) ;
52  ///< Constructor for a start()able object. The two trailing
53  ///< parameters are passed to the G::NewProcess class.
54 
55  ~Task() ;
56  ///< Destructor. Kills the spawned process and waits for it to
57  ///< terminate, where necessary.
58 
59  void start( const G::ExecutableCommand & commandline ) ;
60  ///< Starts the task by spawning a new process with the given
61  ///< command-line and also starting a thread to wait for it. The
62  ///< wait thread signals completion of the child process via the
63  ///< event loop and the TaskCallback interface. Throws Busy if
64  ///< still busy from a prior call to start().
65 
66  void stop() ;
67  ///< Attempts to kill the spawned process and waits for it
68  ///< to terminate. No task-done callback will be triggered.
69 
70 private:
71  Task( const Task & ) ;
72  void operator=( const Task & ) ;
73  friend class GNet::TaskImp ;
74  void done( int exit_code , std::string output ) ;
75  void exception( std::exception & ) ;
76 
77 private:
78  unique_ptr<TaskImp> m_imp ;
79  TaskCallback & m_callback ;
80  ExceptionHandler & m_eh ;
81  std::string m_exec_error_format ;
82  G::Identity m_id ;
83  bool m_busy ;
84 } ;
85 
86 /// \class GNet::TaskCallback
87 /// An abstract interface for callbacks from GNet::Task.
88 ///
90 {
91 public:
92  virtual void onTaskDone( int exit_status , const std::string & output ) = 0 ;
93  ///< Callback function to signal task completion.
94 
95 protected:
96  virtual ~TaskCallback() ;
97  ///< Destructor.
98 
99 private:
100  void operator=( const TaskCallback & ) ;
101 } ;
102 
103 #endif
Network classes.
Definition: gaddress.h:29
static Identity invalid()
Returns an invalid identity.
Task(TaskCallback &, ExceptionHandler &eh, const std::string &exec_error_format=std::string(), const G::Identity &=G::Identity::invalid())
Constructor for a start()able object.
Definition: gtask.cpp:148
A combination of user-id and group-id, with a very low-level interface to the get/set/e/uid/gid funct...
Definition: gidentity.h:42
void start(const G::ExecutableCommand &commandline)
Starts the task by spawning a new process with the given command-line and also starting a thread to w...
Definition: gtask.cpp:162
A private implementation class used by GNet::Task.
Definition: gtask.cpp:31
An abstract interface for handling exceptions thrown out of event-loop callbacks (socket events...
void stop()
Attempts to kill the spawned process and waits for it to terminate.
Definition: gtask.cpp:171
virtual void onTaskDone(int exit_status, const std::string &output)=0
Callback function to signal task completion.
A class for running an exectuable in a separate process with an asychronous completion callback...
Definition: gtask.h:42
A structure representing an external program, holding a path and a set of arguments.
An abstract interface for callbacks from GNet::Task.
Definition: gtask.h:89
~Task()
Destructor.
Definition: gtask.cpp:158
virtual ~TaskCallback()
Destructor.
Definition: gtask.cpp:186