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