E-MailRelay

gtask.h
Go to the documentation of this file.
1//
2// Copyright (C) 2001-2021 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 "genvironment.h"
27#include "gnewprocess.h"
28#include "gexceptionsink.h"
29#include "gidentity.h"
30#include "gexecutablecommand.h"
31#include <memory>
32
33 namespace GNet
34{
35 class Task ;
36 class TaskImp ;
37 class TaskCallback ;
38}
39
40//| \class GNet::Task
41/// A class for running an exectuable in a separate process with an asychronous
42/// completion callback.
43///
44 class GNet::Task
45{
46 public:
47 G_EXCEPTION( Busy , "cannot execute command-line task: still busy from last time" ) ;
48
49 Task( TaskCallback & , ExceptionSink es ,
50 const std::string & exec_error_format = std::string() ,
51 const G::Identity & = G::Identity::invalid() ) ;
52 ///< Constructor for an object that can be start()ed or run().
53 ///< The two trailing parameters are passed to the G::NewProcess
54 ///< class.
55
56 ~Task() ;
57 ///< Destructor. Kills the spawned process and waits for it to
58 ///< terminate, where necessary.
59
60 void start( const G::ExecutableCommand & commandline ) ;
61 ///< Starts the task by spawning a new process with the given
62 ///< command-line and also starting a thread to wait for it. The
63 ///< wait thread signals completion of the child process via the
64 ///< event loop and the TaskCallback interface. Standard
65 ///< output goes to the pipe and standard error is discarded.
66 ///< Throws Busy if still busy from a prior call to start().
67
68 void start( const G::ExecutableCommand & commandline , const G::Environment & env ,
69 G::NewProcess::Fd fd_stdin = G::NewProcess::Fd::devnull() ,
70 G::NewProcess::Fd fd_stdout = G::NewProcess::Fd::pipe() ,
71 G::NewProcess::Fd fd_stderr = G::NewProcess::Fd::devnull() ,
72 const G::Path & cd = G::Path() ) ;
73 ///< Overload with more control over the execution
74 ///< environment. See also G::NewProcess.
75
76 void stop() ;
77 ///< Attempts to kill the spawned process. No task-done
78 ///< callback will be triggered.
79
80 std::pair<int,std::string> run( const G::ExecutableCommand & commandline , const G::Environment & env ,
81 G::NewProcess::Fd fd_stdin = G::NewProcess::Fd::devnull() ,
82 G::NewProcess::Fd fd_stdout = G::NewProcess::Fd::pipe() ,
83 G::NewProcess::Fd fd_stderr = G::NewProcess::Fd::devnull() ,
84 const G::Path & cd = G::Path() ) ;
85 ///< Runs the task synchronously and returns the exit code
86 ///< and pipe output. Throws if killed. The callback interface
87 ///< is not used.
88
89 public:
90 Task( const Task & ) = delete ;
91 Task( Task && ) = delete ;
92 void operator=( const Task & ) = delete ;
93 void operator=( Task && ) = delete ;
94
95 private:
96 friend class GNet::TaskImp ;
97 void done( int exit_code , const std::string & output ) ;
98 void exception( std::exception & ) ;
99
100 private:
101 std::unique_ptr<TaskImp> m_imp ;
102 TaskCallback & m_callback ;
103 ExceptionSink m_es ;
104 std::string m_exec_error_format ;
105 G::Identity m_id ;
106 bool m_busy ;
107} ;
108
109//| \class GNet::TaskCallback
110/// An abstract interface for callbacks from GNet::Task.
111///
112 class GNet::TaskCallback
113{
114 public:
115 virtual ~TaskCallback() = default ;
116 ///< Destructor.
117
118 virtual void onTaskDone( int exit_status , const std::string & pipe_output ) = 0 ;
119 ///< Callback function to signal task completion.
120} ;
121
122#endif
GNet::ExceptionSink
A tuple containing an ExceptionHandler interface pointer and a bound 'exception source' pointer.
Definition: gexceptionsink.h:100
GNet::TaskCallback
An abstract interface for callbacks from GNet::Task.
Definition: gtask.h:113
GNet::TaskCallback::~TaskCallback
virtual ~TaskCallback()=default
Destructor.
GNet::TaskCallback::onTaskDone
virtual void onTaskDone(int exit_status, const std::string &pipe_output)=0
Callback function to signal task completion.
GNet::TaskImp
A private implementation class used by GNet::Task.
Definition: gtask.cpp:36
GNet::Task
A class for running an exectuable in a separate process with an asychronous completion callback.
Definition: gtask.h:45
GNet::Task::Task
Task(TaskCallback &, ExceptionSink es, const std::string &exec_error_format=std::string(), const G::Identity &=G::Identity::invalid())
Constructor for an object that can be start()ed or run().
Definition: gtask.cpp:229
GNet::Task::~Task
~Task()
Destructor.
Definition: gtask.cpp:239
GNet::Task::stop
void stop()
Attempts to kill the spawned process.
Definition: gtask.cpp:250
GNet::Task::start
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:273
GNet::Task::run
std::pair< int, std::string > run(const G::ExecutableCommand &commandline, const G::Environment &env, G::NewProcess::Fd fd_stdin=G::NewProcess::Fd::devnull(), G::NewProcess::Fd fd_stdout=G::NewProcess::Fd::pipe(), G::NewProcess::Fd fd_stderr=G::NewProcess::Fd::devnull(), const G::Path &cd=G::Path())
Runs the task synchronously and returns the exit code and pipe output.
Definition: gtask.cpp:259
G::Environment
Holds a set of environment variables and also provides static methods to wrap getenv() and putenv().
Definition: genvironment.h:39
G::ExecutableCommand
A structure representing an external program, holding a path and a set of arguments.
Definition: gexecutablecommand.h:44
G::Identity
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:43
G::Identity::invalid
static Identity invalid() noexcept
Returns an invalid identity.
Definition: gidentity_unix.cpp:159
G::Path
A Path object represents a file system path.
Definition: gpath.h:72
genvironment.h
geventhandler.h
gexceptionsink.h
gexecutablecommand.h
gidentity.h
gnewprocess.h
GNet
Network classes.
Definition: gdef.h:1115
G::NewProcess::Fd
Wraps up a file descriptor for passing to G::NewProcess.
Definition: gnewprocess.h:77