E-MailRelay

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