OpenShot Library | OpenShotAudio  0.2.2
juce_ConnectedChildProcess.h
1 
2 /** @weakgroup juce_events-interprocess
3  * @{
4  */
5 /*
6  ==============================================================================
7 
8  This file is part of the JUCE library.
9  Copyright (c) 2017 - ROLI Ltd.
10 
11  JUCE is an open source library subject to commercial or open-source
12  licensing.
13 
14  The code included in this file is provided under the terms of the ISC license
15  http://www.isc.org/downloads/software-support-policy/isc-license. Permission
16  To use, copy, modify, and/or distribute this software for any purpose with or
17  without fee is hereby granted provided that the above copyright notice and
18  this permission notice appear in all copies.
19 
20  JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
21  EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
22  DISCLAIMED.
23 
24  ==============================================================================
25 */
26 
27 namespace juce
28 {
29 
30 //==============================================================================
31 /**
32  Acts as the slave end of a master/slave pair of connected processes.
33 
34  The ChildProcessSlave and ChildProcessMaster classes make it easy for an app
35  to spawn a child process, and to manage a 2-way messaging connection to control it.
36 
37  To use the system, you need to create subclasses of both ChildProcessSlave and
38  ChildProcessMaster. To instantiate the ChildProcessSlave object, you must
39  add some code to your main() or JUCEApplication::initialise() function that
40  calls the initialiseFromCommandLine() method to check the app's command-line
41  parameters to see whether it's being launched as a child process. If this returns
42  true then the slave process can be allowed to run, and its handleMessageFromMaster()
43  method will be called whenever a message arrives.
44 
45  The juce demo app has a good example of this class in action.
46 
47  @see ChildProcessMaster, InterprocessConnection, ChildProcess
48 
49  @tags{Events}
50 */
52 {
53 public:
54  /** Creates a non-connected slave process.
55  Use initialiseFromCommandLine to connect to a master process.
56  */
58 
59  /** Destructor. */
60  virtual ~ChildProcessSlave();
61 
62  /** This checks some command-line parameters to see whether they were generated by
63  ChildProcessMaster::launchSlaveProcess(), and if so, connects to that master process.
64 
65  In an exe that can be used as a child process, you should add some code to your
66  main() or JUCEApplication::initialise() that calls this method.
67 
68  The commandLineUniqueID should be a short alphanumeric identifier (no spaces!)
69  that matches the string passed to ChildProcessMaster::launchSlaveProcess().
70 
71  The timeoutMs parameter lets you specify how long the child process is allowed
72  to run without receiving a ping from the master before the master is considered to
73  have died, and handleConnectionLost() will be called. Passing <= 0 for this timeout
74  makes it use a default value.
75 
76  Returns true if the command-line matches and the connection is made successfully.
77  */
78  bool initialiseFromCommandLine (const String& commandLine,
79  const String& commandLineUniqueID,
80  int timeoutMs = 0);
81 
82  //==============================================================================
83  /** This will be called to deliver messages from the master process.
84  The call will probably be made on a background thread, so be careful with your
85  thread-safety! You may want to respond by sending back a message with
86  sendMessageToMaster()
87  */
88  virtual void handleMessageFromMaster (const MemoryBlock&) = 0;
89 
90  /** This will be called when the master process finishes connecting to this slave.
91  The call will probably be made on a background thread, so be careful with your thread-safety!
92  */
93  virtual void handleConnectionMade();
94 
95  /** This will be called when the connection to the master process is lost.
96  The call may be made from any thread (including the message thread).
97  Typically, if your process only exists to act as a slave, you should probably exit
98  when this happens.
99  */
100  virtual void handleConnectionLost();
101 
102  /** Tries to send a message to the master process.
103  This returns true if the message was sent, but doesn't check that it actually gets
104  delivered at the other end. If successful, the data will emerge in a call to your
105  ChildProcessMaster::handleMessageFromSlave().
106  */
107  bool sendMessageToMaster (const MemoryBlock&);
108 
109 private:
110  struct Connection;
111  std::unique_ptr<Connection> connection;
112 
113  JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (ChildProcessSlave)
114 };
115 
116 //==============================================================================
117 /**
118  Acts as the master in a master/slave pair of connected processes.
119 
120  The ChildProcessSlave and ChildProcessMaster classes make it easy for an app
121  to spawn a child process, and to manage a 2-way messaging connection to control it.
122 
123  To use the system, you need to create subclasses of both ChildProcessSlave and
124  ChildProcessMaster. When you want your master process to launch the slave, you
125  just call launchSlaveProcess(), and it'll attempt to launch the executable that
126  you specify (which may be the same exe), and assuming it has been set-up to
127  correctly parse the command-line parameters (see ChildProcessSlave) then a
128  two-way connection will be created.
129 
130  The juce demo app has a good example of this class in action.
131 
132  @see ChildProcessSlave, InterprocessConnection, ChildProcess
133 
134  @tags{Events}
135 */
137 {
138 public:
139  /** Creates an uninitialised master process object.
140  Use launchSlaveProcess to launch and connect to a child process.
141  */
143 
144  /** Destructor.
145  Note that the destructor calls killSlaveProcess(), but doesn't wait for
146  the child process to finish terminating.
147  */
148  virtual ~ChildProcessMaster();
149 
150  /** Attempts to launch and connect to a slave process.
151  This will start the given executable, passing it a special command-line
152  parameter based around the commandLineUniqueID string, which must be a
153  short alphanumeric string (no spaces!) that identifies your app. The exe
154  that gets launched must respond by calling ChildProcessSlave::initialiseFromCommandLine()
155  in its startup code, and must use a matching ID to commandLineUniqueID.
156 
157  The timeoutMs parameter lets you specify how long the child process is allowed
158  to go without sending a ping before it is considered to have died and
159  handleConnectionLost() will be called. Passing <= 0 for this timeout makes
160  it use a default value.
161 
162  If this all works, the method returns true, and you can begin sending and
163  receiving messages with the slave process.
164 
165  If a child process is already running, this will call killSlaveProcess() and
166  start a new one.
167  */
168  bool launchSlaveProcess (const File& executableToLaunch,
169  const String& commandLineUniqueID,
170  int timeoutMs = 0,
171  int streamFlags = ChildProcess::wantStdOut | ChildProcess::wantStdErr);
172 
173  /** Sends a kill message to the slave, and disconnects from it.
174  Note that this won't wait for it to terminate.
175  */
176  void killSlaveProcess();
177 
178  /** This will be called to deliver a message from the slave process.
179  The call will probably be made on a background thread, so be careful with your thread-safety!
180  */
181  virtual void handleMessageFromSlave (const MemoryBlock&) = 0;
182 
183  /** This will be called when the slave process dies or is somehow disconnected.
184  The call will probably be made on a background thread, so be careful with your thread-safety!
185  */
186  virtual void handleConnectionLost();
187 
188  /** Attempts to send a message to the slave process.
189  This returns true if the message was dispatched, but doesn't check that it actually
190  gets delivered at the other end. If successful, the data will emerge in a call to
191  your ChildProcessSlave::handleMessageFromMaster().
192  */
193  bool sendMessageToSlave (const MemoryBlock&);
194 
195 private:
196  std::unique_ptr<ChildProcess> childProcess;
197 
198  struct Connection;
199  std::unique_ptr<Connection> connection;
200 
201  JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (ChildProcessMaster)
202 };
203 
204 } // namespace juce
205 
206 /** @}*/
#define JUCE_API
This macro is added to all JUCE public class declarations.
Acts as the slave end of a master/slave pair of connected processes.
Acts as the master in a master/slave pair of connected processes.
The JUCE String class!
Definition: juce_String.h:42
Represents a local file or directory.
Definition: juce_File.h:44
A class to hold a resizable block of raw data.