4 * Copyright 2002 the LyX Team
5 * Read the file COPYING
7 * \author Asger Alstrup
9 * Interface cleaned up by
10 * \author Angus Leeming <a.leeming@ic.ac.uk>
12 * An instance of Class Forkedcall represents a single child process.
14 * Class Forkedcall uses fork() and execvp() to lauch the child process.
16 * Once launched, control is returned immediately to the parent process
17 * but a Signal can be emitted upon completion of the child.
19 * The child process is not killed when the Forkedcall instance goes out of
20 * scope, but it can be killed by an explicit invocation of the kill() member
32 #include <sys/types.h>
33 #include <boost/smart_ptr.hpp>
34 #include <sigc++/signal_system.h>
50 /** Start the child process.
52 * The command "what" is passed to fork() for execution.
54 * There are two startscript commands available. They differ in that
55 * the second receives a signal that is executed on completion of
56 * the command. This makes sense only for a command executed
57 * in the background, ie DontWait.
59 * The other startscript command can be executed either blocking
60 * or non-blocking, but no signal will be emitted on finishing.
62 int startscript(Starttype, string const & what);
64 /** A SignalType signal is can be emitted once the forked process
65 * has finished. It passes:
66 * the commandline string;
67 * the PID of the child and;
68 * the return value from the child.
70 * We use a signal rather than simply a callback function so that
71 * we can return easily to C++ methods, rather than just globally
72 * accessible functions.
74 typedef SigC::Signal3<void, string const &, pid_t, int> SignalType;
76 /** The signal is connected in the calling routine to the desired
77 * slot. We pass a shared_ptr rather than a reference to the signal
78 * because it is eminently possible for the instance of the calling
79 * class (and hence the signal) to be destructed before the forked
82 * It doesn't matter if the slot disappears, SigC takes care of that.
84 typedef boost::shared_ptr<SignalType> SignalTypePtr;
87 int startscript(string const & what, SignalTypePtr);
89 /** Invoking the following methods makes sense only if the command
90 * is running asynchronously!
93 /** gets the PID of the child process.
96 pid_t pid() const { return pid_; }
103 /** Set the return value of the child process.
106 void setRetValue(int r) { retval_ = r; }
108 /** Kill child prematurely.
109 * First, a SIGHUP is sent to the child.
110 * If that does not end the child process within "tolerance"
111 * seconds, the SIGKILL signal is sent to the child.
112 * When the child is dead, the callback is called.
114 void kill(int tolerance = 5);
116 string const & command() const { return command_; }
119 /// Callback function
120 SignalTypePtr signal_;
125 /// Process ID of child
128 /// Return value from child
132 pid_t generateChild();
134 /// Wait for child process to finish. Updates returncode from child.
138 #endif // FORKEDCALL_H