|
1 |
| -package net.datenwerke.async; |
2 |
| - |
3 |
| -import java.util.List; |
4 |
| -import java.util.concurrent.Callable; |
5 |
| -import java.util.concurrent.ExecutorService; |
6 |
| -import java.util.concurrent.Future; |
7 |
| -import java.util.concurrent.ThreadPoolExecutor; |
8 |
| -import java.util.concurrent.TimeUnit; |
9 |
| - |
10 |
| -/** |
11 |
| - * A thread pool allowing to run asynchronous tasks. |
12 |
| - * |
13 |
| - * |
14 |
| - */ |
15 |
| -public interface DwAsyncPool { |
16 |
| - |
17 |
| - /** |
18 |
| - * Submits a value-returning task for execution and returns a Future |
19 |
| - * representing the pending results of the task. The Future's <tt>get</tt> |
20 |
| - * method will return the task's result upon successful completion. |
21 |
| - * |
22 |
| - * @see ExecutorService#submit(Callable) |
23 |
| - * @param task |
24 |
| - */ |
25 |
| - public <T> Future<T> submit(Callable<T> task); |
26 |
| - |
27 |
| - /** |
28 |
| - * Submits a Runnable task for execution and returns a Future representing that |
29 |
| - * task. The Future's <tt>get</tt> method will return <tt>null</tt> upon |
30 |
| - * <em>successful</em> completion. |
31 |
| - * |
32 |
| - * @see ExecutorService#submit(Runnable) |
33 |
| - * @param task |
34 |
| - */ |
35 |
| - public <T> Future<T> submit(Runnable task); |
36 |
| - |
37 |
| - /** |
38 |
| - * Submits a Runnable task for execution and returns a Future representing that |
39 |
| - * task. The Future's <tt>get</tt> method will return the given result upon |
40 |
| - * successful completion. |
41 |
| - * |
42 |
| - * @see ExecutorService#submit(Runnable, Object) |
43 |
| - * @param task |
44 |
| - */ |
45 |
| - public <T> Future<T> submit(Runnable task, T result); |
46 |
| - |
47 |
| - /** |
48 |
| - * Returns the approximate number of threads that are actively executing tasks. |
49 |
| - * |
50 |
| - * @see ThreadPoolExecutor#getActiveCount() |
51 |
| - * @return the number of threads |
52 |
| - */ |
53 |
| - int getActiveCount(); |
54 |
| - |
55 |
| - /** |
56 |
| - * Returns the approximate total number of tasks that have ever been scheduled |
57 |
| - * for execution. Because the states of tasks and threads may change dynamically |
58 |
| - * during computation, the returned value is only an approximation. |
59 |
| - * |
60 |
| - * @see ThreadPoolExecutor#getTaskCount() |
61 |
| - * @return the number of threads |
62 |
| - */ |
63 |
| - long getTaskCount(); |
64 |
| - |
65 |
| - /** |
66 |
| - * Returns the approximate total number of tasks that have completed execution. |
67 |
| - * Because the states of tasks and threads may change dynamically during |
68 |
| - * computation, the returned value is only an approximation, but one that does |
69 |
| - * not ever decrease across successive calls. |
70 |
| - * |
71 |
| - * @see ThreadPoolExecutor#getCompletedTaskCount() |
72 |
| - * @return the number of threads |
73 |
| - */ |
74 |
| - long getCompletedTaskCount(); |
75 |
| - |
76 |
| - /** |
77 |
| - * Returns the current number of threads in the pool. |
78 |
| - * |
79 |
| - * @see ThreadPoolExecutor#getPoolSize() |
80 |
| - * @return the number of threads |
81 |
| - */ |
82 |
| - int getPoolSize(); |
83 |
| - |
84 |
| - /** |
85 |
| - * Returns the core number of threads. |
86 |
| - * |
87 |
| - * @see ThreadPoolExecutor#getCorePoolSize() |
88 |
| - * @return the core number of threads |
89 |
| - */ |
90 |
| - int getCorePoolSize(); |
91 |
| - |
92 |
| - /** |
93 |
| - * Returns true if the pool has been shut down (orderly). |
94 |
| - */ |
95 |
| - boolean isShutdown(); |
96 |
| - |
97 |
| - /** |
98 |
| - * Returns true if the pool has been terminated |
99 |
| - */ |
100 |
| - boolean isTerminated(); |
101 |
| - |
102 |
| - /** |
103 |
| - * Blocks until all tasks have completed execution after a shutdown request, or |
104 |
| - * the timeout occurs, or the current thread is interrupted, whichever happens |
105 |
| - * first. |
106 |
| - * |
107 |
| - * @see ExecutorService#awaitTermination(long, TimeUnit) |
108 |
| - * @param timeout |
109 |
| - * @param unit |
110 |
| - * @throws InterruptedException |
111 |
| - */ |
112 |
| - boolean awaitTermination(long timeout, TimeUnit unit) throws InterruptedException; |
113 |
| - |
114 |
| - /** |
115 |
| - * Initiates an orderly shutdown in which previously submitted tasks are |
116 |
| - * executed, but no new tasks will be accepted. Invocation has no additional |
117 |
| - * effect if already shut down. |
118 |
| - * |
119 |
| - * <p> |
120 |
| - * This method does not wait for previously submitted tasks to complete |
121 |
| - * execution. Use {@link #awaitTermination awaitTermination} to do that. |
122 |
| - * |
123 |
| - * @see ExecutorService#shutdown() |
124 |
| - */ |
125 |
| - void shutdown(); |
126 |
| - |
127 |
| - /** |
128 |
| - * Attempts to stop all actively executing tasks, halts the processing of |
129 |
| - * waiting tasks, and returns a list of the tasks that were awaiting execution. |
130 |
| - * |
131 |
| - * <p> |
132 |
| - * This method does not wait for actively executing tasks to terminate. Use |
133 |
| - * {@link #awaitTermination awaitTermination} to do that. |
134 |
| - * |
135 |
| - * <p> |
136 |
| - * There are no guarantees beyond best-effort attempts to stop processing |
137 |
| - * actively executing tasks. For example, typical implementations will cancel |
138 |
| - * via {@link Thread#interrupt}, so any task that fails to respond to interrupts |
139 |
| - * may never terminate. |
140 |
| - * |
141 |
| - * @see ExecutorService#shutdownNow() |
142 |
| - * |
143 |
| - * @return list of tasks that never commenced execution |
144 |
| - */ |
145 |
| - List<Runnable> shutdownNow(); |
146 |
| - |
147 |
| -} |
| 1 | +package net.datenwerke.async; |
| 2 | + |
| 3 | +import java.util.List; |
| 4 | +import java.util.concurrent.Callable; |
| 5 | +import java.util.concurrent.ExecutorService; |
| 6 | +import java.util.concurrent.Future; |
| 7 | +import java.util.concurrent.ThreadPoolExecutor; |
| 8 | +import java.util.concurrent.TimeUnit; |
| 9 | + |
| 10 | +/** |
| 11 | + * A thread pool allowing to run asynchronous tasks. |
| 12 | + * |
| 13 | + * |
| 14 | + */ |
| 15 | +public interface DwAsyncPool { |
| 16 | + |
| 17 | + /** |
| 18 | + * Submits a value-returning task for execution and returns a Future |
| 19 | + * representing the pending results of the task. The Future's <tt>get</tt> |
| 20 | + * method will return the task's result upon successful completion. |
| 21 | + * |
| 22 | + * @see ExecutorService#submit(Callable) |
| 23 | + * @param task |
| 24 | + */ |
| 25 | + public <T> Future<T> submit(Callable<T> task); |
| 26 | + |
| 27 | + /** |
| 28 | + * Submits a Runnable task for execution and returns a Future representing that |
| 29 | + * task. The Future's <tt>get</tt> method will return <tt>null</tt> upon |
| 30 | + * <em>successful</em> completion. |
| 31 | + * |
| 32 | + * @see ExecutorService#submit(Runnable) |
| 33 | + * @param task |
| 34 | + */ |
| 35 | + public <T> Future<T> submit(Runnable task); |
| 36 | + |
| 37 | + /** |
| 38 | + * Submits a Runnable task for execution and returns a Future representing that |
| 39 | + * task. The Future's <tt>get</tt> method will return the given result upon |
| 40 | + * successful completion. |
| 41 | + * |
| 42 | + * @see ExecutorService#submit(Runnable, Object) |
| 43 | + * @param task |
| 44 | + */ |
| 45 | + public <T> Future<T> submit(Runnable task, T result); |
| 46 | + |
| 47 | + /** |
| 48 | + * Returns the approximate number of threads that are actively executing tasks. |
| 49 | + * |
| 50 | + * @see ThreadPoolExecutor#getActiveCount() |
| 51 | + * @return the number of threads |
| 52 | + */ |
| 53 | + int getActiveCount(); |
| 54 | + |
| 55 | + /** |
| 56 | + * Returns the approximate total number of tasks that have ever been scheduled |
| 57 | + * for execution. Because the states of tasks and threads may change dynamically |
| 58 | + * during computation, the returned value is only an approximation. |
| 59 | + * |
| 60 | + * @see ThreadPoolExecutor#getTaskCount() |
| 61 | + * @return the number of threads |
| 62 | + */ |
| 63 | + long getTaskCount(); |
| 64 | + |
| 65 | + /** |
| 66 | + * Returns the approximate total number of tasks that have completed execution. |
| 67 | + * Because the states of tasks and threads may change dynamically during |
| 68 | + * computation, the returned value is only an approximation, but one that does |
| 69 | + * not ever decrease across successive calls. |
| 70 | + * |
| 71 | + * @see ThreadPoolExecutor#getCompletedTaskCount() |
| 72 | + * @return the number of threads |
| 73 | + */ |
| 74 | + long getCompletedTaskCount(); |
| 75 | + |
| 76 | + /** |
| 77 | + * Returns the current number of threads in the pool. |
| 78 | + * |
| 79 | + * @see ThreadPoolExecutor#getPoolSize() |
| 80 | + * @return the number of threads |
| 81 | + */ |
| 82 | + int getPoolSize(); |
| 83 | + |
| 84 | + /** |
| 85 | + * Returns the core number of threads. |
| 86 | + * |
| 87 | + * @see ThreadPoolExecutor#getCorePoolSize() |
| 88 | + * @return the core number of threads |
| 89 | + */ |
| 90 | + int getCorePoolSize(); |
| 91 | + |
| 92 | + /** |
| 93 | + * Returns true if the pool has been shut down (orderly). |
| 94 | + */ |
| 95 | + boolean isShutdown(); |
| 96 | + |
| 97 | + /** |
| 98 | + * Returns true if the pool has been terminated |
| 99 | + */ |
| 100 | + boolean isTerminated(); |
| 101 | + |
| 102 | + /** |
| 103 | + * Blocks until all tasks have completed execution after a shutdown request, or |
| 104 | + * the timeout occurs, or the current thread is interrupted, whichever happens |
| 105 | + * first. |
| 106 | + * |
| 107 | + * @see ExecutorService#awaitTermination(long, TimeUnit) |
| 108 | + * @param timeout |
| 109 | + * @param unit |
| 110 | + * @throws InterruptedException |
| 111 | + */ |
| 112 | + boolean awaitTermination(long timeout, TimeUnit unit) throws InterruptedException; |
| 113 | + |
| 114 | + /** |
| 115 | + * Initiates an orderly shutdown in which previously submitted tasks are |
| 116 | + * executed, but no new tasks will be accepted. Invocation has no additional |
| 117 | + * effect if already shut down. |
| 118 | + * |
| 119 | + * <p> |
| 120 | + * This method does not wait for previously submitted tasks to complete |
| 121 | + * execution. Use {@link #awaitTermination awaitTermination} to do that. |
| 122 | + * |
| 123 | + * @see ExecutorService#shutdown() |
| 124 | + */ |
| 125 | + void shutdown(); |
| 126 | + |
| 127 | + /** |
| 128 | + * Attempts to stop all actively executing tasks, halts the processing of |
| 129 | + * waiting tasks, and returns a list of the tasks that were awaiting execution. |
| 130 | + * |
| 131 | + * <p> |
| 132 | + * This method does not wait for actively executing tasks to terminate. Use |
| 133 | + * {@link #awaitTermination awaitTermination} to do that. |
| 134 | + * |
| 135 | + * <p> |
| 136 | + * There are no guarantees beyond best-effort attempts to stop processing |
| 137 | + * actively executing tasks. For example, typical implementations will cancel |
| 138 | + * via {@link Thread#interrupt}, so any task that fails to respond to interrupts |
| 139 | + * may never terminate. |
| 140 | + * |
| 141 | + * @see ExecutorService#shutdownNow() |
| 142 | + * |
| 143 | + * @return list of tasks that never commenced execution |
| 144 | + */ |
| 145 | + List<Runnable> shutdownNow(); |
| 146 | + |
| 147 | +} |
0 commit comments