1 /*
2 * Copyright 2012 The Netty Project
3 *
4 * The Netty Project licenses this file to you under the Apache License,
5 * version 2.0 (the "License"); you may not use this file except in compliance
6 * with the License. You may obtain a copy of the License at:
7 *
8 * https://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13 * License for the specific language governing permissions and limitations
14 * under the License.
15 */
16 package io.netty.util.concurrent;
17
18 import java.util.concurrent.Callable;
19 import java.util.concurrent.TimeUnit;
20
21 /**
22 * The {@link EventExecutor} is a special {@link EventExecutorGroup} which comes
23 * with some handy methods to see if a {@link Thread} is executed in a event loop.
24 * Besides this, it also extends the {@link EventExecutorGroup} to allow for a generic
25 * way to access methods.
26 */
27 public interface EventExecutor extends EventExecutorGroup {
28
29 /**
30 * Return the {@link EventExecutorGroup} which is the parent of this {@link EventExecutor},
31 */
32 EventExecutorGroup parent();
33
34 /**
35 * Calls {@link #inEventLoop(Thread)} with {@link Thread#currentThread()} as argument
36 */
37 default boolean inEventLoop() {
38 return inEventLoop(Thread.currentThread());
39 }
40
41 /**
42 * Return {@code true} if the given {@link Thread} is executed in the event loop,
43 * {@code false} otherwise.
44 */
45 boolean inEventLoop(Thread thread);
46
47 /**
48 * Return a new {@link Promise}.
49 */
50 default <V> Promise<V> newPromise() {
51 return new DefaultPromise<>(this);
52 }
53
54 /**
55 * Create a new {@link ProgressivePromise}.
56 */
57 default <V> ProgressivePromise<V> newProgressivePromise() {
58 return new DefaultProgressivePromise<>(this);
59 }
60
61 /**
62 * Create a new {@link Future} which is marked as succeeded already. So {@link Future#isSuccess()}
63 * will return {@code true}. All {@link FutureListener} added to it will be notified directly. Also
64 * every call of blocking methods will just return without blocking.
65 */
66 default <V> Future<V> newSucceededFuture(V result) {
67 return new SucceededFuture<>(this, result);
68 }
69
70 /**
71 * Create a new {@link Future} which is marked as failed already. So {@link Future#isSuccess()}
72 * will return {@code false}. All {@link FutureListener} added to it will be notified directly. Also
73 * every call of blocking methods will just return without blocking.
74 */
75 default <V> Future<V> newFailedFuture(Throwable cause) {
76 return new FailedFuture<>(this, cause);
77 }
78
79 /**
80 * Returns {@code true} if the {@link EventExecutor} is considered suspended.
81 *
82 * @return {@code true} if suspended, {@code false} otherwise.
83 */
84 default boolean isSuspended() {
85 return false;
86 }
87
88 /**
89 * Try to suspend this {@link EventExecutor} and return {@code true} if suspension was successful.
90 * Suspending an {@link EventExecutor} will allow it to free up resources, like for example a {@link Thread} that
91 * is backing the {@link EventExecutor}. Once an {@link EventExecutor} was suspended it will be started again
92 * by submitting work to it via one of the following methods:
93 * <ul>
94 * <li>{@link #execute(Runnable)}</li>
95 * <li>{@link #schedule(Runnable, long, TimeUnit)}</li>
96 * <li>{@link #schedule(Callable, long, TimeUnit)}</li>
97 * <li>{@link #scheduleAtFixedRate(Runnable, long, long, TimeUnit)}</li>
98 * <li>{@link #scheduleWithFixedDelay(Runnable, long, long, TimeUnit)}</li>
99 * </ul>
100 *
101 * Even if this method returns {@code true} it might take some time for the {@link EventExecutor} to fully suspend
102 * itself.
103 *
104 * @return {@code true} if suspension was successful, otherwise {@code false}.
105 */
106 default boolean trySuspend() {
107 return false;
108 }
109 }