sample/java.util.concurrent.Executors.txt

   1 *java.util.concurrent.Executors* *Executors* Factory and utility methods forExec
   2
   3 public class Executors
   4   extends    |java.lang.Object|
   5
   6 |java.util.concurrent.Executors_Description|
   7 |java.util.concurrent.Executors_Fields|
   8 |java.util.concurrent.Executors_Constructors|
   9 |java.util.concurrent.Executors_Methods|
  10
  11 ================================================================================
  12
  13 *java.util.concurrent.Executors_Methods*
  14 |java.util.concurrent.Executors.callable(PrivilegedAction)|Returns aCallableobj
  15 |java.util.concurrent.Executors.callable(PrivilegedExceptionAction)|Returns aCa
  16 |java.util.concurrent.Executors.callable(Runnable)|Returns aCallableobject that
  17 |java.util.concurrent.Executors.callable(Runnable,T)|Returns aCallableobject th
  18 |java.util.concurrent.Executors.defaultThreadFactory()|Returns a default thread
  19 |java.util.concurrent.Executors.newCachedThreadPool()|Creates a thread pool tha
  20 |java.util.concurrent.Executors.newCachedThreadPool(ThreadFactory)|Creates a th
  21 |java.util.concurrent.Executors.newFixedThreadPool(int)|Creates a thread pool t
  22 |java.util.concurrent.Executors.newFixedThreadPool(int,ThreadFactory)|Creates a
  23 |java.util.concurrent.Executors.newScheduledThreadPool(int)|Creates a thread po
  24 |java.util.concurrent.Executors.newScheduledThreadPool(int,ThreadFactory)|Creat
  25 |java.util.concurrent.Executors.newSingleThreadExecutor()|Creates an Executor t
  26 |java.util.concurrent.Executors.newSingleThreadExecutor(ThreadFactory)|Creates
  27 |java.util.concurrent.Executors.newSingleThreadScheduledExecutor()|Creates a si
  28 |java.util.concurrent.Executors.newSingleThreadScheduledExecutor(ThreadFactory)|
  29 |java.util.concurrent.Executors.privilegedCallable(Callable)|Returns aCallableo
  30 |java.util.concurrent.Executors.privilegedCallableUsingCurrentClassLoader(Callable)|
  31 |java.util.concurrent.Executors.privilegedThreadFactory()|Returns a thread fact
  32 |java.util.concurrent.Executors.unconfigurableExecutorService(ExecutorService)|
  33 |java.util.concurrent.Executors.unconfigurableScheduledExecutorService(ScheduledExecutorService)|
  34
  35 *java.util.concurrent.Executors_Description*
  36
  37 Factory and utility methods for (|java.util.concurrent.Executor|) ,
  38 (|java.util.concurrent.ExecutorService|) ,
  39 (|java.util.concurrent.ScheduledExecutorService|) ,
  40 (|java.util.concurrent.ThreadFactory|) , and (|java.util.concurrent.Callable|)
  41 classes defined in this package. This class supports the following kinds of
  42 methods:
  43
  44 Methods that create and return an (|java.util.concurrent.ExecutorService|) set
  45 up with commonly useful configuration settings. Methods that create and return
  46 a (|java.util.concurrent.ScheduledExecutorService|) set up with commonly useful
  47 configuration settings. Methods that create and return a "wrapped"
  48 ExecutorService, that disables reconfiguration by making
  49 implementation-specific methods inaccessible. Methods that create and return a
  50 (|java.util.concurrent.ThreadFactory|) that sets newly created threads to a
  51 known state. Methods that create and return a (|java.util.concurrent.Callable|)
  52 out of other closure-like forms, so they can be used in execution methods
  53 requiring Callable.
  54
  55
  56 *java.util.concurrent.Executors.callable(PrivilegedAction)*
  57
  58 public static |java.util.concurrent.Callable| callable(java.security.PrivilegedAction action)
  59
  60 Returns a (|java.util.concurrent.Callable|) object that, when called, runs the
  61 given privileged action and returns its result.
  62
  63     action - the privileged action to run
  64
  65     Returns: a callable object
  66 *java.util.concurrent.Executors.callable(PrivilegedExceptionAction)*
  67
  68 public static |java.util.concurrent.Callable| callable(java.security.PrivilegedExceptionAction action)
  69
  70 Returns a (|java.util.concurrent.Callable|) object that, when called, runs the
  71 given privileged exception action and returns its result.
  72
  73     action - the privileged exception action to run
  74
  75     Returns: a callable object
  76 *java.util.concurrent.Executors.callable(Runnable)*
  77
  78 public static |java.util.concurrent.Callable| callable(java.lang.Runnable task)
  79
  80 Returns a (|java.util.concurrent.Callable|) object that, when called, runs the
  81 given task and returns null.
  82
  83     task - the task to run
  84
  85     Returns: a callable object
  86 *java.util.concurrent.Executors.callable(Runnable,T)*
  87
  88 public static |java.util.concurrent.Callable| callable(
  89   java.lang.Runnable task,
  90   java.lang.Object result)
  91
  92 Returns a (|java.util.concurrent.Callable|) object that, when called, runs the
  93 given task and returns the given result. This can be useful when applying
  94 methods requiring a Callable to an otherwise resultless action.
  95
  96     task - the task to run
  97     result - the result to return
  98
  99     Returns: a callable object
 100 *java.util.concurrent.Executors.defaultThreadFactory()*
 101
 102 public static |java.util.concurrent.ThreadFactory| defaultThreadFactory()
 103
 104 Returns a default thread factory used to create new threads. This factory
 105 creates all new threads used by an Executor in the same
 106 (|java.lang.ThreadGroup|) . If there is a (|java.lang.SecurityManager|) , it
 107 uses the group of (|java.lang.System|) , else the group of the thread invoking
 108 this defaultThreadFactory method. Each new thread is created as a non-daemon
 109 thread with priority Thread.NORM_PRIORITY. New threads have names accessible
 110 via (|java.lang.Thread|) of pool-N-thread-M, where N is the sequence number of
 111 this factory, and M is the sequence number of the thread created by this
 112 factory.
 113
 114
 115     Returns: a thread factory
 116 *java.util.concurrent.Executors.newCachedThreadPool()*
 117
 118 public static |java.util.concurrent.ExecutorService| newCachedThreadPool()
 119
 120 Creates a thread pool that creates new threads as needed, but will reuse
 121 previously constructed threads when they are available. These pools will
 122 typically improve the performance of programs that execute many short-lived
 123 asynchronous tasks. Calls to execute will reuse previously constructed threads
 124 if available. If no existing thread is available, a new thread will be created
 125 and added to the pool. Threads that have not been used for sixty seconds are
 126 terminated and removed from the cache. Thus, a pool that remains idle for long
 127 enough will not consume any resources. Note that pools with similar properties
 128 but different details (for example, timeout parameters) may be created using
 129 (|java.util.concurrent.ThreadPoolExecutor|) constructors.
 130
 131
 132     Returns: the newly created thread pool
 133 *java.util.concurrent.Executors.newCachedThreadPool(ThreadFactory)*
 134
 135 public static |java.util.concurrent.ExecutorService| newCachedThreadPool(java.util.concurrent.ThreadFactory threadFactory)
 136
 137 Creates a thread pool that creates new threads as needed, but will reuse
 138 previously constructed threads when they are available, and uses the provided
 139 ThreadFactory to create new threads when needed.
 140
 141     threadFactory - the factory to use when creating new threads
 142
 143     Returns: the newly created thread pool
 144 *java.util.concurrent.Executors.newFixedThreadPool(int)*
 145
 146 public static |java.util.concurrent.ExecutorService| newFixedThreadPool(int nThreads)
 147
 148 Creates a thread pool that reuses a fixed set of threads operating off a shared
 149 unbounded queue. If any thread terminates due to a failure during execution
 150 prior to shutdown, a new one will take its place if needed to execute
 151 subsequent tasks.
 152
 153     nThreads - the number of threads in the pool
 154
 155     Returns: the newly created thread pool
 156 *java.util.concurrent.Executors.newFixedThreadPool(int,ThreadFactory)*
 157
 158 public static |java.util.concurrent.ExecutorService| newFixedThreadPool(
 159   int nThreads,
 160   java.util.concurrent.ThreadFactory threadFactory)
 161
 162 Creates a thread pool that reuses a fixed set of threads operating off a shared
 163 unbounded queue, using the provided ThreadFactory to create new threads when
 164 needed.
 165
 166     nThreads - the number of threads in the pool
 167     threadFactory - the factory to use when creating new threads
 168
 169     Returns: the newly created thread pool
 170 *java.util.concurrent.Executors.newScheduledThreadPool(int)*
 171
 172 public static |java.util.concurrent.ScheduledExecutorService| newScheduledThreadPool(int corePoolSize)
 173
 174 Creates a thread pool that can schedule commands to run after a given delay, or
 175 to execute periodically.
 176
 177     corePoolSize - the number of threads to keep in the pool, even if they are idle.
 178
 179     Returns: a newly created scheduled thread pool
 180 *java.util.concurrent.Executors.newScheduledThreadPool(int,ThreadFactory)*
 181
 182 public static |java.util.concurrent.ScheduledExecutorService| newScheduledThreadPool(
 183   int corePoolSize,
 184   java.util.concurrent.ThreadFactory threadFactory)
 185
 186 Creates a thread pool that can schedule commands to run after a given delay, or
 187 to execute periodically.
 188
 189     corePoolSize - the number of threads to keep in the pool, even if they are idle.
 190     threadFactory - the factory to use when the executor creates a new thread.
 191
 192     Returns: a newly created scheduled thread pool
 193 *java.util.concurrent.Executors.newSingleThreadExecutor()*
 194
 195 public static |java.util.concurrent.ExecutorService| newSingleThreadExecutor()
 196
 197 Creates an Executor that uses a single worker thread operating off an unbounded
 198 queue. (Note however that if this single thread terminates due to a failure
 199 during execution prior to shutdown, a new one will take its place if needed to
 200 execute subsequent tasks.) Tasks are guaranteed to execute sequentially, and no
 201 more than one task will be active at any given time. Unlike the otherwise
 202 equivalent newFixedThreadPool(1) the returned executor is guaranteed not to be
 203 reconfigurable to use additional threads.
 204
 205
 206     Returns: the newly created single-threaded Executor
 207 *java.util.concurrent.Executors.newSingleThreadExecutor(ThreadFactory)*
 208
 209 public static |java.util.concurrent.ExecutorService| newSingleThreadExecutor(java.util.concurrent.ThreadFactory threadFactory)
 210
 211 Creates an Executor that uses a single worker thread operating off an unbounded
 212 queue, and uses the provided ThreadFactory to create a new thread when needed.
 213 Unlike the otherwise equivalent newFixedThreadPool(1, threadFactory) the
 214 returned executor is guaranteed not to be reconfigurable to use additional
 215 threads.
 216
 217     threadFactory - the factory to use when creating new threads
 218
 219     Returns: the newly created single-threaded Executor
 220 *java.util.concurrent.Executors.newSingleThreadScheduledExecutor()*
 221
 222 public static |java.util.concurrent.ScheduledExecutorService| newSingleThreadScheduledExecutor()
 223
 224 Creates a single-threaded executor that can schedule commands to run after a
 225 given delay, or to execute periodically. (Note however that if this single
 226 thread terminates due to a failure during execution prior to shutdown, a new
 227 one will take its place if needed to execute subsequent tasks.) Tasks are
 228 guaranteed to execute sequentially, and no more than one task will be active at
 229 any given time. Unlike the otherwise equivalent newScheduledThreadPool(1) the
 230 returned executor is guaranteed not to be reconfigurable to use additional
 231 threads.
 232
 233
 234     Returns: the newly created scheduled executor
 235 *java.util.concurrent.Executors.newSingleThreadScheduledExecutor(ThreadFactory)*
 236
 237 public static |java.util.concurrent.ScheduledExecutorService| newSingleThreadScheduledExecutor(java.util.concurrent.ThreadFactory threadFactory)
 238
 239 Creates a single-threaded executor that can schedule commands to run after a
 240 given delay, or to execute periodically. (Note however that if this single
 241 thread terminates due to a failure during execution prior to shutdown, a new
 242 one will take its place if needed to execute subsequent tasks.) Tasks are
 243 guaranteed to execute sequentially, and no more than one task will be active at
 244 any given time. Unlike the otherwise equivalent newScheduledThreadPool(1,
 245 threadFactory) the returned executor is guaranteed not to be reconfigurable to
 246 use additional threads.
 247
 248     threadFactory - the factory to use when creating new threads
 249
 250     Returns: a newly created scheduled executor
 251 *java.util.concurrent.Executors.privilegedCallable(Callable)*
 252
 253 public static |java.util.concurrent.Callable| privilegedCallable(java.util.concurrent.Callable callable)
 254
 255 Returns a (|java.util.concurrent.Callable|) object that will, when called,
 256 execute the given callable under the current access control context. This
 257 method should normally be invoked within an (|java.security.AccessController|)
 258 action to create callables that will, if possible, execute under the selected
 259 permission settings holding within that action; or if not possible, throw an
 260 associated (|java.security.AccessControlException|) .
 261
 262     callable - the underlying task
 263
 264     Returns: a callable object
 265 *java.util.concurrent.Executors.privilegedCallableUsingCurrentClassLoader(Callable)*
 266
 267 public static |java.util.concurrent.Callable| privilegedCallableUsingCurrentClassLoader(java.util.concurrent.Callable callable)
 268
 269 Returns a (|java.util.concurrent.Callable|) object that will, when called,
 270 execute the given callable under the current access control context, with the
 271 current context class loader as the context class loader. This method should
 272 normally be invoked within an (|java.security.AccessController|) action to
 273 create callables that will, if possible, execute under the selected permission
 274 settings holding within that action; or if not possible, throw an associated
 275 (|java.security.AccessControlException|) .
 276
 277     callable - the underlying task
 278
 279     Returns: a callable object
 280 *java.util.concurrent.Executors.privilegedThreadFactory()*
 281
 282 public static |java.util.concurrent.ThreadFactory| privilegedThreadFactory()
 283
 284 Returns a thread factory used to create new threads that have the same
 285 permissions as the current thread. This factory creates threads with the same
 286 settings as (|java.util.concurrent.Executors|) , additionally setting the
 287 AccessControlContext and contextClassLoader of new threads to be the same as
 288 the thread invoking this privilegedThreadFactory method. A new
 289 privilegedThreadFactory can be created within an
 290 (|java.security.AccessController|) action setting the current thread's access
 291 control context to create threads with the selected permission settings holding
 292 within that action.
 293
 294 Note that while tasks running within such threads will have the same access
 295 control and class loader settings as the current thread, they need not have the
 296 same (|java.lang.ThreadLocal|) or (|java.lang.InheritableThreadLocal|) values.
 297 If necessary, particular values of thread locals can be set or reset before any
 298 task runs in (|java.util.concurrent.ThreadPoolExecutor|) subclasses using
 299 (|java.util.concurrent.ThreadPoolExecutor|) . Also, if it is necessary to
 300 initialize worker threads to have the same InheritableThreadLocal settings as
 301 some other designated thread, you can create a custom ThreadFactory in which
 302 that thread waits for and services requests to create others that will inherit
 303 its values.
 304
 305
 306     Returns: a thread factory
 307 *java.util.concurrent.Executors.unconfigurableExecutorService(ExecutorService)*
 308
 309 public static |java.util.concurrent.ExecutorService| unconfigurableExecutorService(java.util.concurrent.ExecutorService executor)
 310
 311 Returns an object that delegates all defined
 312 (|java.util.concurrent.ExecutorService|) methods to the given executor, but not
 313 any other methods that might otherwise be accessible using casts. This provides
 314 a way to safely "freeze" configuration and disallow tuning of a given concrete
 315 implementation.
 316
 317     executor - the underlying implementation
 318
 319     Returns: an ExecutorService instance
 320 *java.util.concurrent.Executors.unconfigurableScheduledExecutorService(ScheduledExecutorService)*
 321
 322 public static |java.util.concurrent.ScheduledExecutorService| unconfigurableScheduledExecutorService(java.util.concurrent.ScheduledExecutorService executor)
 323
 324 Returns an object that delegates all defined
 325 (|java.util.concurrent.ScheduledExecutorService|) methods to the given
 326 executor, but not any other methods that might otherwise be accessible using
 327 casts. This provides a way to safely "freeze" configuration and disallow tuning
 328 of a given concrete implementation.
 329
 330     executor - the underlying implementation
 331
 332     Returns: a ScheduledExecutorService instance
 333