Medical Imaging Interaction Toolkit  2018.4.99-12ad79a3
Medical Imaging Interaction Toolkit
berryIJobManager.h
Go to the documentation of this file.
1 /*============================================================================
2 
3 The Medical Imaging Interaction Toolkit (MITK)
4 
5 Copyright (c) German Cancer Research Center (DKFZ)
6 All rights reserved.
7 
8 Use of this source code is governed by a 3-clause BSD license that can be
9 found in the LICENSE file.
10 
11 ============================================================================*/
12 
13 #ifndef _BERRY_IJOBMANAGER_H
14 #define _BERRY_IJOBMANAGER_H
15 
16 #include<string>
17 
19 
20 #include "berryJob.h"
21 #include "berryProgressProvider.h"
22 #include "berryIProgressMonitor.h"
24 
25 #include<Poco/Thread.h>
26 
27 namespace berry
28 {
29 
55 {
56 
58 
59 
67  static const std::string PROP_USE_DAEMON_THREADS ;
68 
77  virtual void AddJobChangeListener(IJobChangeListener* listener) = 0;
78 
80  // * Begins applying this rule in the calling thread. If the rule conflicts with another
81  // * rule currently running in another thread, this method blocks until there are
82  // * no conflicting rules. Calls to <tt>beginRule</tt> must eventually be followed
83  // * by a matching call to <tt>endRule</tt> in the same thread and with the identical
84  // * rule instance.
85  // * <p>
86  // * Rules can be nested only if the rule for the inner <tt>beginRule</tt>
87  // * is contained within the rule for the outer <tt>beginRule</tt>. Rule containment
88  // * is tested with the API method <tt>ISchedulingRule.contains</tt>. Also, begin/end
89  // * pairs must be strictly nested. Only the rule that has most recently begun
90  // * can be ended at any given time.
91  // * <p>
92  // * A rule of <code>null</code> can be used, but will be ignored for scheduling
93  // * purposes. The outermost non-null rule in the thread will be used for scheduling. A
94  // * <code>null</code> rule that is begun must still be ended.
95  // * <p>
96  // * If this method is called from within a job that has a scheduling rule, the
97  // * given rule must also be contained within the rule for the running job.
98  // * <p>
99  // * Note that <tt>endRule</tt> must be called even if <tt>beginRule</tt> fails.
100  // * The recommended usage is:
101  // * <pre>
102  // * final ISchedulingRule rule = ...;
103  // * try {
104  // * manager.beginRule(rule, monitor);
105  // * } finally {
106  // * manager.endRule(rule);
107  // * }
108  // * </pre>
109  // *
110  // * @param rule the rule to begin applying in this thread, or <code>null</code>
111  // * @param monitor a progress monitor, or <code>null</code> if progress
112  // * reporting and cancellation are not desired
113  // * @throws IllegalArgumentException if the rule is not strictly nested within
114  // * all other rules currently active for this thread
115  // * @throws OperationCanceledException if the supplied monitor reports cancelation
116  // * before the rule becomes available
117  // * @see ISchedulingRule#contains(ISchedulingRule)
118  // */
119 
121 
123  // * Cancels all jobs in the given job family. Jobs in the family that are currently waiting
124  // * will be removed from the queue. Sleeping jobs will be discarded without having
125  // * a chance to wake up. Currently executing jobs will be asked to cancel but there
126  // * is no guarantee that they will do so.
127  // *
128  // * @param family the job family to cancel, or <code>null</code> to cancel all jobs
129  // * @see Job#belongsTo(Object)
130  // */
132 
163  virtual IProgressMonitor::Pointer CreateProgressGroup() = 0;
164 
166  // * Returns the job that is currently running in this thread, or <code>null</code> if there
167  // * is no currently running job.
168  // *
169  // * @return the job or <code>null</code>
170  // */
172 
174  // * Ends the application of a rule to the calling thread. Calls to <tt>endRule</tt>
175  // * must be preceded by a matching call to <tt>beginRule</tt> in the same thread
176  // * with an identical rule instance.
177  // * <p>
178  // * Rules can be nested only if the rule for the inner <tt>beginRule</tt>
179  // * is contained within the rule for the outer <tt>beginRule</tt>. Also, begin/end
180  // * pairs must be strictly nested. Only the rule that has most recently begun
181  // * can be ended at any given time.
182  // *
183  // * @param rule the rule to end applying in this thread
184  // * @throws IllegalArgumentException if this method is called on a rule for which
185  // * there is no matching begin, or that does not match the most recent begin.
186  // * @see ISchedulingRule#contains(ISchedulingRule)
187  // */
189 
191  // * Returns all waiting, executing and sleeping jobs belonging
192  // * to the given family. If no jobs are found, an empty array is returned.
193  // *
194  // * @param family the job family to find, or <code>null</code> to find all jobs
195  // * @return the job array
196  // * @see Job#belongsTo(Object)
197  // */
199 
208  virtual bool IsIdle()= 0;
209 
219  virtual bool IsSuspended() = 0;
220 
222  // * Waits until all jobs of the given family are finished. This method will block the
223  // * calling thread until all such jobs have finished executing, or until this thread is
224  // * interrupted. If there are no jobs in
225  // * the family that are currently waiting, running, or sleeping, this method returns
226  // * immediately. Feedback on how the join is progressing is provided to a progress
227  // * monitor.
228  // * <p>
229  // * If this method is called while the job manager is suspended, only jobs
230  // * that are currently running will be joined; Once there are no jobs
231  // * in the family in the {@link Job#RUNNING} state, this method returns.
232  // * </p>
233  // * <p>
234  // * Note that there is a deadlock risk when using join. If the calling thread owns
235  // * a lock or object monitor that the joined thread is waiting for, deadlock
236  // * will occur. This method can also result in starvation of the current thread if
237  // * another thread continues to add jobs of the given family, or if a
238  // * job in the given family reschedules itself in an infinite loop.
239  // * </p>
240  // *
241  // * @param family the job family to join, or <code>null</code> to join all jobs.
242  // * @param monitor Progress monitor for reporting progress on how the
243  // * wait is progressing, or <code>null</code> if no progress monitoring is required.
244  // * @exception InterruptedException if this thread is interrupted while waiting
245  // * @exception OperationCanceledException if the progress monitor is canceled while waiting
246  // * @see Job#belongsTo(Object)
247  // * @see #suspend()
248  // */
252  // * Creates a new lock object. All lock objects supplied by the job manager
253  // * know about each other and will always avoid circular deadlock amongst
254  // * themselves.
255  // *
256  // * @return the new lock object
257  // */
259 
268  virtual void RemoveJobChangeListener(IJobChangeListener* listener) = 0;
269 
271  // * Resumes execution of jobs after a previous <code>suspend</code>. All
272  // * jobs that were sleeping or waiting prior to the suspension, or that were
273  // * scheduled while the job manager was suspended, will now be eligible
274  // * for execution.
275  // * <p>
276  // * Calling this method on a rule that is not suspended has no effect. If another
277  // * thread also owns the rule at the time this method is called, then the rule will
278  // * not be resumed until all threads have released the rule.
279  // *
280  // * @deprecated This method is not safe and should not be used.
281  // * Suspending a scheduling rule violates the thread safety
282  // * of clients that use scheduling rules as a mutual exclusion mechanism,
283  // * and can result in concurrency problems in all clients that use the suspended rule.
284  // * @see #suspend(ISchedulingRule, IProgressMonitor)
285  // */
287 
289  // * Resumes execution of jobs after a previous <code>suspend</code>. All
290  // * jobs that were sleeping or waiting prior to the suspension, or that were
291  // * scheduled while the job manager was suspended, will now be eligible
292  // * for execution.
293  // * <p>
294  // * Calling <code>resume</code> when the job manager is not suspended
295  // * has no effect.
296  // *
297  // * @see #suspend()
298  // * @see #isSuspended()
299  // */
301 
303  // * Provides a hook that is notified whenever a thread is about to wait on a lock,
304  // * or when a thread is about to release a lock. This hook must only be set once.
305  // * <p>
306  // * This method is for internal use by the platform-related plug-ins.
307  // * Clients should not call this method.
308  // * </p>
309  // * @see LockListener
310  // */
311  // TODO LockListener .. SetLockListener
313 
325  virtual void SetProgressProvider(ProgressProvider::Pointer) = 0;
326 
349  // virtual void Suspend() = 0;
350 
352  // * Defers execution of all jobs with scheduling rules that conflict with the
353  // * given rule. The caller will be blocked until all currently executing jobs with
354  // * conflicting rules are completed. Conflicting jobs that are sleeping or waiting at
355  // * the time this method is called will not be executed until the rule is resumed.
356  // * <p>
357  // * While a rule is suspended, all calls to <code>beginRule</code> and
358  // * <code>endRule</code> on a suspended rule will not block the caller.
359  // * The rule remains suspended until a subsequent call to
360  // * <code>resume(ISchedulingRule)</code> with the identical rule instance.
361  // * Further calls to <code>suspend</code> with an identical rule prior to calling
362  // * <code>resume</code> are ignored.
363  // * </p>
364  // * <p>
365  // * This method is long-running; progress and cancelation are provided by
366  // * the given progress monitor. In the case of cancelation, the rule will
367  // * not be suspended.
368  // * </p>
369  // * Note: this very powerful function should be used with extreme caution.
370  // * Suspending rules will prevent jobs in the system from executing, which may
371  // * have adverse effects on components that are relying on execution of jobs.
372  // * The job manager should never be suspended without intent to resume
373  // * execution soon afterwards. Deadlock will result if the thread responsible
374  // * for resuming the rule attempts to join a suspended job.
375  // *
376  // * @deprecated This method is not safe and should not be used.
377  // * Suspending a scheduling rule violates the thread safety
378  // * of clients that use scheduling rules as a mutual exclusion mechanism,
379  // * and can result in concurrency problems in all clients that use the suspended rule.
380  // * @param rule The scheduling rule to suspend. Must not be <code>null</code>.
381  // * @param monitor a progress monitor, or <code>null</code> if progress
382  // * reporting is not desired
383  // * @exception OperationCanceledException if the operation is canceled.
384  // * Cancelation can occur even if no progress monitor is provided.
385  // * @see #resume(ISchedulingRule)
386  // */
388 
390  // * Requests that all jobs in the given job family be suspended. Jobs currently
391  // * waiting to be run will be removed from the queue and moved into the
392  // * <code>SLEEPING</code> state. Jobs that have been put to sleep
393  // * will remain in that state until either resumed or canceled. This method has
394  // * no effect on jobs that are not currently waiting to be run.
395  // * <p>
396  // * Sleeping jobs can be resumed using <code>wakeUp</code>.
397  // *
398  // * @param family the job family to sleep, or <code>null</code> to sleep all jobs.
399  // * @see Job#belongsTo(Object)
400  // */
402 
404  // * Transfers ownership of a scheduling rule to another thread. The identical
405  // * scheduling rule must currently be owned by the calling thread as a result of
406  // * a previous call to <code>beginRule</code>. The destination thread must
407  // * not already own a scheduling rule.
408  // * <p>
409  // * Calling this method is equivalent to atomically calling <code>endRule</code>
410  // * in the calling thread followed by an immediate <code>beginRule</code> in
411  // * the destination thread. The destination thread is responsible for subsequently
412  // * calling <code>endRule</code> when it is finished using the rule.
413  // * <p>
414  // * This method has no effect when the destination thread is the same as the
415  // * calling thread.
416  // *
417  // * @param rule The scheduling rule to transfer
418  // * @param destinationThread The new owner for the transferred rule.
419  // * @since 3.1
420  // */
422 
424  // * Resumes scheduling of all sleeping jobs in the given family. This method
425  // * has no effect on jobs in the family that are not currently sleeping.
426  // *
427  // * @param family the job family to wake up, or <code>null</code> to wake up all jobs
428  // * @see Job#belongsTo(Object)
429  // */
431 
432 
433 };
434 
435 }
436 #endif /* IJOBMANAGER */
#define BERRY_JOBS
Light weight base class for most BlueBerry classes.
Definition: berryObject.h:72
#define berryObjectMacro(...)
Definition: berryMacros.h:33