1 /*
2 * Copyright 2024 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.channel;
17
18 /**
19 * Handles IO dispatching for an {@link IoEventLoop}
20 * All operations except {@link #wakeup(IoEventLoop)} and {@link #isCompatible(Class)} <strong>MUST</strong> be executed
21 * on the {@link IoEventLoop} thread and should never be called from the user-directly.
22 * <p>
23 * Once a {@link IoHandle} is registered via the {@link #register(IoEventLoop, IoHandle)} method it's possible
24 * to submit {@link IoOps} related to the {@link IoHandle} via {@link IoRegistration#submit(IoOps)}.
25 * These submitted {@link IoOps} are the "source" of {@link IoEvent}s that are dispatched to the registered
26 * {@link IoHandle} via the {@link IoHandle#handle(IoRegistration, IoEvent)} method.
27 * These events must be consumed (and handled) as otherwise they might be reported again until handled.
28 *
29 */
30 public interface IoHandler {
31 /**
32 * Run the IO handled by this {@link IoHandler}. The {@link IoExecutionContext} should be used
33 * to ensure we not execute too long and so block the processing of other task that are
34 * scheduled on the {@link EventLoop}. This is done by taking {@link IoExecutionContext#delayNanos(long)} or
35 * {@link IoExecutionContext#deadlineNanos()} into account.
36 *
37 * @return the number of {@link IoHandle} for which I/O was handled.
38 */
39 int run(IoExecutionContext context);
40
41 /**
42 * Prepare to destroy this {@link IoHandler}. This method will be called before {@link #destroy()} and may be
43 * called multiple times.
44 */
45 void prepareToDestroy();
46
47 /**
48 * Destroy the {@link IoHandler} and free all its resources. Once destroyed using the {@link IoHandler} will
49 * cause undefined behaviour.
50 */
51 void destroy();
52
53 /**
54 * Register a {@link IoHandle} for IO.
55 *
56 * @param eventLoop the {@link IoEventLoop} that did issue the registration.
57 * @param handle the {@link IoHandle} to register.
58 * @throws Exception thrown if an error happens during registration.
59 */
60 IoRegistration register(IoEventLoop eventLoop, IoHandle handle) throws Exception;
61
62 /**
63 * Wakeup the {@link IoHandler}, which means if any operation blocks it should be unblocked and
64 * return as soon as possible.
65 */
66 void wakeup(IoEventLoop eventLoop);
67
68 /**
69 * Returns {@code true} if the given type is compatible with this {@link IoHandler} and so can be registered,
70 * {@code false} otherwise.
71 *
72 * @param handleType the type of the {@link IoHandle}.
73 * @return if compatible of not.
74 */
75 boolean isCompatible(Class<? extends IoHandle> handleType);
76 }