HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
UT_WritePipe.h
Go to the documentation of this file.
1 /*
2  * PROPRIETARY INFORMATION. This software is proprietary to
3  * Side Effects Software Inc., and is not to be reproduced,
4  * transmitted, or disclosed in any way without written permission.
5  *
6  * NAME: UT_WritePipe.h ( UT Library, C++)
7  *
8  * COMMENTS: This is a write pipe which allows you to poll the pipe to see
9  * if the child process has completed. It works almost exactly
10  * like popen/pclose except for a few things:
11  * 1: You can easily get the pid of the child
12  * 2: The close() method has an option to not block
13  * and return even if the child is running.
14  *
15  * CAVEATS: This class does not work for read pipes, but then again, read
16  * pipes don't have the problem of blocking on the child
17  * process...
18  */
19 
20 #ifndef __UT_WritePipe__
21 #define __UT_WritePipe__
22 
23 #include "UT_API.h"
24 #include <sys/types.h>
25 #include <stdio.h>
26 #include "UT_Lock.h"
27 #include "UT_SysClone.h"
28 
30 public:
31  /// Construct pipe
32  ///
33  /// @param cmd If given, opens the cmd before returning. Call getFilePtr()
34  /// for the actual created file handle.
35  /// @param change_process_group Puts the child process in a new process
36  /// group to isolate the parent from any
37  /// crashes coming from the child.
38  explicit UT_WritePipe(const char *cmd = 0,
39  bool change_process_group = false);
40 
41  /// Destruct pipe
42  ///
43  /// If the pipe is open and destructed, the process will be blocked until
44  /// the child is terminated.
45  ~UT_WritePipe();
46 
47  /// Open a command as a write pipe. The file descriptor returned will be
48  /// the command's stdin.
49  FILE *open(const char *cmd)
50  { return open(cmd, NULL, NULL); }
51 
52  /// Open a command as a write pipe. The file descriptor returned will be
53  /// the command's stdin. If the @c kid_stdout file descriptor is given,
54  /// this will become stdout for the child. If @c kid_stderr is specified,
55  /// it will be come stderr for the child.
56  FILE *open(const char *cmd,
57  FILE *kid_stdout,
58  FILE *kid_stderr);
59 
60  /// Close the pipe
61  ///
62  /// @return Return values are:
63  /// - -1 : Error closing the pipe
64  /// - 0 : Child is still running (only returned if the arg is 0)
65  /// - >0 : Child is terminated
66  ///
67  /// @note After close is called, it is not safe to write to the pipe
68  /// anymore (since the file descriptor is closed). Please use isComplete()
69  /// to see if the child process has terminated.
70  int close(bool wait_for_child_to_terminate = false);
71 
72  /// Call this to find out whether it's safe to close (i.e. the child process
73  /// has terminated). This can be called before, or after the pipe has been
74  /// closed.
75  bool isComplete(bool block = false);
76 
77  /// Suspend pipe process
78  void suspend();
79 
80  /// Restart pipe process after suspended
81  void restart();
82 
83  /// Terminate pipe process
84  ///
85  /// @warning This method is asynchronous! `close(/*block*/false)` is liable
86  /// to return false if you call it right after this. Use
87  /// `isComplete(/*block*/true)` to ensure the pipe process is fully
88  /// complete before continuing, or call `close()` with block set to true.
89  void terminate();
90 
91  /// Is pipe process suspended?
92  bool isSuspended() const;
93 
94  /// Return file handle for last open() call
95  FILE *getFilePtr() { return myFilePtr; }
96 
97  /// If close() fails, you can get the errno of the fail call by calling
98  /// this method. If the child is still running, the error will be
99  /// set to EWOULDBLOCK
100  int getErrno() const { return myErrno; }
101 
102  /// If close() succeeds, you can get the exit status of the child process by
103  /// calling the following method.
104  int getStatus() const { return myExitStatus; }
105 
106  /// This method will return the child process id.
107  pid_t getPid() const { return myPid; }
108 
109 private:
110 #ifdef WIN32
111  FILE *doPOpen( char *cmd, FILE *kstdout, FILE *kstderr );
112  int isCompleteImpl(bool block);
113 #endif
114 
115 private:
116  FILE *myFilePtr;
117  int myErrno;
118  int myExitStatus;
119  unsigned myFlag;
120  pid_t myPid;
121  bool myChangeProcessGroup;
122 #ifdef WIN32
123  void *myHThread;
124  void *myHProcess;
125  void *myPipe;
126 #else
127  UT_Lock myCompleteLock;
128 #endif
129 };
130 
131 #endif
132 
pid_t getPid() const
This method will return the child process id.
Definition: UT_WritePipe.h:107
FILE * open(const char *cmd)
Definition: UT_WritePipe.h:49
int getStatus() const
Definition: UT_WritePipe.h:104
#define UT_API
Definition: UT_API.h:13
void close() override
FILE * getFilePtr()
Return file handle for last open() call.
Definition: UT_WritePipe.h:95
int open(float queuesize) override
int getErrno() const
Definition: UT_WritePipe.h:100