001/* 002 * ==================================================================== 003 * Licensed to the Apache Software Foundation (ASF) under one 004 * or more contributor license agreements. See the NOTICE file 005 * distributed with this work for additional information 006 * regarding copyright ownership. The ASF licenses this file 007 * to you under the Apache License, Version 2.0 (the 008 * "License"); you may not use this file except in compliance 009 * with the License. You may obtain a copy of the License at 010 * 011 * http://www.apache.org/licenses/LICENSE-2.0 012 * 013 * Unless required by applicable law or agreed to in writing, 014 * software distributed under the License is distributed on an 015 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 016 * KIND, either express or implied. See the License for the 017 * specific language governing permissions and limitations 018 * under the License. 019 * ==================================================================== 020 * 021 * This software consists of voluntary contributions made by many 022 * individuals on behalf of the Apache Software Foundation. For more 023 * information on the Apache Software Foundation, please see 024 * <http://www.apache.org/>. 025 * 026 */ 027 028package org.apache.http.nio.reactor; 029 030import java.io.IOException; 031 032/** 033 * HttpCore NIO is based on the Reactor pattern as described by Doug Lea. 034 * The purpose of I/O reactors is to react to I/O events and to dispatch event 035 * notifications to individual I/O sessions. The main idea of I/O reactor 036 * pattern is to break away from the one thread per connection model imposed 037 * by the classic blocking I/O model. 038 * <p> 039 * The IOReactor interface represents an abstract object implementing 040 * the Reactor pattern. 041 * <p> 042 * I/O reactors usually employ a small number of dispatch threads (often as 043 * few as one) to dispatch I/O event notifications to a much greater number 044 * (often as many as several thousands) of I/O sessions or connections. It is 045 * generally recommended to have one dispatch thread per CPU core. 046 * 047 * @since 4.0 048 */ 049public interface IOReactor { 050 051 /** 052 * Returns the current status of the reactor. 053 * 054 * @return reactor status. 055 */ 056 IOReactorStatus getStatus(); 057 058 /** 059 * Starts the reactor and initiates the dispatch of I/O event notifications 060 * to the given {@link IOEventDispatch}. 061 * 062 * @param eventDispatch the I/O event dispatch. 063 * @throws IOException in case of an I/O error. 064 */ 065 void execute(IOEventDispatch eventDispatch) 066 throws IOException; 067 068 /** 069 * Initiates shutdown of the reactor and blocks approximately for the given 070 * period of time in milliseconds waiting for the reactor to terminate all 071 * active connections, to shut down itself and to release system resources 072 * it currently holds. 073 * 074 * @param waitMs wait time in milliseconds. 075 * @throws IOException in case of an I/O error. 076 */ 077 void shutdown(long waitMs) 078 throws IOException; 079 080 /** 081 * Initiates shutdown of the reactor and blocks for a default period of 082 * time waiting for the reactor to terminate all active connections, to shut 083 * down itself and to release system resources it currently holds. It is 084 * up to individual implementations to decide for how long this method can 085 * remain blocked. 086 * 087 * @throws IOException in case of an I/O error. 088 */ 089 void shutdown() 090 throws IOException; 091 092}