1 /**
2 * AUTOHIT 2003
3 * Copyright Erich P Gatejen (c) 1989,1997,2003,2004
4 *
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or (at
8 * your option) any later version.
9 * This program is distributed in the hope that it will be useful, but
10 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
11 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
12 * more details.
13 *
14 * You should have received a copy of the GNU General Public License along
15 * with this program; if not, write to the Free Software Foundation, Inc.,
16 * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
17 *
18 * Additional license information can be found in the documentation.
19 * @author Erich P Gatejen
20 */
21 package autohit.vm;
22
23 import autohit.server.SystemContext;
24
25 /**
26 * This defines the interface to a process controller.
27 * <p>
28 * BE SURE to .init() this controller BEFORE any other threads
29 * access its methods (particularly execute()). Some implementations
30 * my be bases on Threads. Be sure to .start() after init()
31 * Failure to heed this
32 * warning COULD result in a race condition... :-)
33 * <p><pre>
34 * There are four "commands" to a process controller:
35 * - PAUSE will hold execution
36 * - RESUME will restart execution
37 * - STOP will stop execution of the VM and dump it
38 * - KILL will stop the execution and let this process die!
39 * </pre>
40 * @version 1.0
41 * <i>Version History</i>
42 * <code>EPG - New - 24Jul03 </code>
43 */
44 public interface VMProcess {
45
46 /**
47 * Initialize the process controller. It takes an immutable SystemContext.
48 * @param sctx a ready SystemContext. This will be fed to all controlled processes.
49 * @param setpid the pid
50 * @throws VMException is the process goes bad
51 * @see autohit.vm.VM
52 */
53 public void init(SystemContext sctx, int setpid) throws VMException;
54
55 /**
56 * Load and Execute a VM. If a VM is already running, it will return
57 * false. Otherwise, it will return true. Otherwise, it will load it
58 * and give the greenlight to the VM thread.
59 * <p>
60 * This method can be called by any thread. It will clear the
61 * request flags.
62 *
63 * @param aVM A fully implimented derived-class of VM.
64 * @return true if successful and execution begun, false if
65 * another VM is already running or there is an error.
66 *
67 * @see autohit.vm.VM
68 */
69 public boolean execute(VM aVM);
70
71 /**
72 * Pause the vm. This may be called by another thread.
73 *
74 * As with vmResume() and vmStop(), it posts a request to the
75 * VMContext. The context will not heed the request until
76 * the current VM.execute() is complete and the context has
77 * a chance to check for these requests.
78 * <p>
79 * There is no rendezvous; the method will not block. All successive
80 * requests count as the same request until the context services
81 * it. There is no guarentee on the timing of the service. The Context
82 * will not check for requests until AFTER the current instruction is complete.
83 * So, if the vm is executing a long wait instruction, it could indeed be
84 * some time before the request is serviced.
85 * <p>
86 * If you need to make sure that the request worked, then use
87 * the verifyState() method to get the definative state of the
88 * VM/Context.
89 * <p>
90 * As for the return value, "success" merely means that the
91 * request was successfully posted and not that the action
92 * was completed.
93 * <p>
94 * One last thaught: this is not a robust OS implimentation of
95 * a thread context. You might want to restrict calls to vmPause()
96 * and vmResume() to a single external thread. Multiple threads
97 * might get confused if they don't cooperate...
98 *
99 * @return true is successful. false if no vm is running or
100 * it is already paused.
101 * @see autohit.vm.VM
102 */
103 public boolean vmPause();
104
105 /**
106 * Resume the vm.
107 * <p>
108 * See the notes for the pause() method.
109 *
110 * @return true is successful. false if no vm is paused or
111 * it is already running.
112 * @see autohit.vm.VM
113 */
114 public boolean vmResume();
115
116 /**
117 * Stop the vm. This will kill it permanently, so be careful.
118 * <p>
119 * See the notes for the pause() method.
120 *
121 * @return true is successful. false if no vm is running or
122 * paused.
123 * @see autohit.vm.VM
124 */
125 public boolean vmStop();
126
127 /**
128 * Get's the PID for this process
129 *
130 * @return pid
131 */
132 public int getPID();
133
134 /**
135 * Get's root program
136 *
137 * @return string name of the root program
138 */
139 public String getRootProgram();
140
141 /**
142 * Kill this context. It is irrevocable as it will interrupt the Thread.
143 * If you want to request the program to stop, call vmStop();
144 * <p>
145 * See the notes for the pause() method.
146 *
147 * @return always returns true.
148 * @see autohit.vm.VM
149 */
150 public boolean kill();
151
152 /**
153 * Verify the state of the VM. It will report a VM state
154 * value as defined in the VM class--VM.State_*. This will
155 * be the authorative state, as this method blocks until the
156 * VM has chance to clear requests and unblock it.
157 * <p>
158 * (And, never EVER call this method from within THIS thread.
159 * You'll almost certainly deadlock it.)
160 * <p>
161 * The following describes each state:
162 * <pre>
163 * STATE_NEW = VM is loaded bu not started
164 * STATE_RUNNING = VM is actively running.
165 * STATE_PAUSED = VM is paused.
166 * STATE_DONE = VM finished execution.
167 * This is rare, as the VM will
168 * be automatically unloaded when
169 * finished.
170 * STATE_NO_VM = No VM is loaded into this context.
171 * </pre>
172 *
173 * @return a VM.State_* value.
174 * @see autohit.vm.VM
175 */
176 public int verifyState();
177
178 /**
179 * A simple request for state. It may or not be stale be the
180 * time the calling thread gets it. If you msut have THE
181 * AUTHORATIVE state, then call verifyState()
182 *
183 * @return a VM.State_* value.
184 * @see autohit.vm.VM
185 */
186 public int getState();
187
188 /**
189 * Get my system context.
190 *
191 * @return a SystemContext
192 * @see autohit.vm.VM
193 */
194 public SystemContext getSystemContext();
195
196 /**
197 * Get a registered process attribute.
198 *
199 * @return an object that matches the name
200 * @see autohit.vm.VM
201 */
202 public Object processAttribute(String name);
203
204 /**
205 * Run the process.
206 */
207 public void run();
208
209
210 /**
211 * Run the process.
212 */
213 public void start();
214
215 /**
216 * Join the process
217 */
218 public void joinIt();
219
220 }
|