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 "UT_Lock.h"
25 #include "UT_NonCopyable.h"
26 #include "UT_SysClone.h"
27 #include <stdio.h>
28 #include <sys/types.h>
29 
31 public:
32  /// Construct pipe
33  ///
34  /// @param cmd If given, opens the cmd before returning. Call getFilePtr()
35  /// for the actual created file handle.
36  /// @param change_process_group Puts the child process in a new process
37  /// group to isolate the parent from any
38  /// crashes coming from the child.
39  explicit UT_WritePipe(const char *cmd = 0,
40  bool change_process_group = false);
41 
42  /// Destruct pipe
43  ///
44  /// If the pipe is open and destructed, the process will be blocked until
45  /// the child is terminated.
46  ~UT_WritePipe();
47 
49 
50  /// Open a command as a write pipe. The file descriptor returned will be
51  /// the command's stdin.
52  FILE *open(const char *cmd)
53  { return open(cmd, NULL, NULL); }
54 
55  /// Open a command as a write pipe. The file descriptor returned will be
56  /// the command's stdin. If the @c kid_stdout file descriptor is given,
57  /// this will become stdout for the child. If @c kid_stderr is specified,
58  /// it will be come stderr for the child.
59  FILE *open(const char *cmd,
60  FILE *kid_stdout,
61  FILE *kid_stderr);
62 
63  /// Close the pipe
64  ///
65  /// @return Return values are:
66  /// - -1 : Error closing the pipe
67  /// - 0 : Child is still running (only returned if the arg is 0)
68  /// - >0 : Child is terminated
69  ///
70  /// @note After close is called, it is not safe to write to the pipe
71  /// anymore (since the file descriptor is closed). Please use isComplete()
72  /// to see if the child process has terminated.
73  int close(bool wait_for_child_to_terminate = false);
74 
75  /// Call this to find out whether it's safe to close (i.e. the child process
76  /// has terminated). This can be called before, or after the pipe has been
77  /// closed.
78  bool isComplete(bool block = false);
79 
80  /// Suspend pipe process
81  void suspend();
82 
83  /// Restart pipe process after suspended
84  void restart();
85 
86  /// Terminate pipe process
87  ///
88  /// @warning This method is asynchronous! `close(/*block*/false)` is liable
89  /// to return false if you call it right after this. Use
90  /// `isComplete(/*block*/true)` to ensure the pipe process is fully
91  /// complete before continuing, or call `close()` with block set to true.
92  void terminate();
93 
94  /// Is pipe process suspended?
95  bool isSuspended() const;
96 
97  /// Return file handle for last open() call
98  FILE *getFilePtr() { return myFilePtr; }
99 
100  /// If close() fails, you can get the errno of the fail call by calling
101  /// this method. If the child is still running, the error will be
102  /// set to EWOULDBLOCK
103  int getErrno() const { return myErrno; }
104 
105  /// If close() succeeds, you can get the exit status of the child process by
106  /// calling the following method.
107  int getStatus() const { return myExitStatus; }
108 
109  /// This method will return the child process id.
110  pid_t getPid() const { return myPid; }
111 
112 private:
113 #ifdef WIN32
114  FILE *doPOpen( char *cmd, FILE *kstdout, FILE *kstderr );
115  int isCompleteImpl(bool block);
116 #endif
117 
118 private:
119  FILE *myFilePtr;
120  int myErrno;
121  int myExitStatus;
122  unsigned myFlag;
123  pid_t myPid;
124  bool myChangeProcessGroup;
125 #ifdef WIN32
126  void *myHThread;
127  void *myHProcess;
128  void *myPipe;
129 #else
130  UT_Lock myCompleteLock;
131 #endif
132 };
133 
134 #endif
135 
pid_t getPid() const
This method will return the child process id.
Definition: UT_WritePipe.h:110
int getStatus() const
Definition: UT_WritePipe.h:107
#define UT_API
Definition: UT_API.h:14
void close() override
FILE * getFilePtr()
Return file handle for last open() call.
Definition: UT_WritePipe.h:98
int open(float queuesize) override
#define UT_NON_COPYABLE(CLASS)
Define deleted copy constructor and assignment operator inside a class.
int getErrno() const
Definition: UT_WritePipe.h:103