2 // ========================================================================
3 // Copyright (c) 1995-2014 Mort Bay Consulting Pty. Ltd.
4 // ------------------------------------------------------------------------
5 // All rights reserved. This program and the accompanying materials
6 // are made available under the terms of the Eclipse Public License v1.0
7 // and Apache License v2.0 which accompanies this distribution.
9 // The Eclipse Public License is available at
10 // http://www.eclipse.org/legal/epl-v10.html
12 // The Apache License v2.0 is available at
13 // http://www.opensource.org/licenses/apache2.0.php
15 // You may elect to redistribute this code under either of these licenses.
16 // ========================================================================
19 package org.eclipse.jetty.io;
21 import java.io.IOException;
22 import java.nio.ByteBuffer;
23 import java.nio.channels.ClosedChannelException;
24 import java.nio.channels.WritePendingException;
25 import java.util.Arrays;
26 import java.util.EnumMap;
27 import java.util.EnumSet;
29 import java.util.concurrent.atomic.AtomicReference;
31 import org.eclipse.jetty.util.BufferUtil;
32 import org.eclipse.jetty.util.Callback;
33 import org.eclipse.jetty.util.log.Log;
34 import org.eclipse.jetty.util.log.Logger;
38 * A Utility class to help implement {@link EndPoint#write(Callback, ByteBuffer...)} by calling
39 * {@link EndPoint#flush(ByteBuffer...)} until all content is written.
40 * The abstract method {@link #onIncompleteFlushed()} is called when not all content has been written after a call to
41 * flush and should organise for the {@link #completeWrite()} method to be called when a subsequent call to flush
42 * should be able to make more progress.
45 abstract public class WriteFlusher
47 private static final Logger LOG = Log.getLogger(WriteFlusher.class);
48 private static final boolean DEBUG = LOG.isDebugEnabled(); // Easy for the compiler to remove the code if DEBUG==false
49 private static final ByteBuffer[] EMPTY_BUFFERS = new ByteBuffer[0];
50 private static final EnumMap<StateType, Set<StateType>> __stateTransitions = new EnumMap<>(StateType.class);
51 private static final State __IDLE = new IdleState();
52 private static final State __WRITING = new WritingState();
53 private static final State __COMPLETING = new CompletingState();
54 private final EndPoint _endPoint;
55 private final AtomicReference<State> _state = new AtomicReference<>();
59 // fill the state machine
60 __stateTransitions.put(StateType.IDLE, EnumSet.of(StateType.WRITING));
61 __stateTransitions.put(StateType.WRITING, EnumSet.of(StateType.IDLE, StateType.PENDING, StateType.FAILED));
62 __stateTransitions.put(StateType.PENDING, EnumSet.of(StateType.COMPLETING,StateType.IDLE));
63 __stateTransitions.put(StateType.COMPLETING, EnumSet.of(StateType.IDLE, StateType.PENDING, StateType.FAILED));
64 __stateTransitions.put(StateType.FAILED, EnumSet.of(StateType.IDLE));
67 // A write operation may either complete immediately:
68 // IDLE-->WRITING-->IDLE
69 // Or it may not completely flush and go via the PENDING state
70 // IDLE-->WRITING-->PENDING-->COMPLETING-->IDLE
71 // Or it may take several cycles to complete
72 // IDLE-->WRITING-->PENDING-->COMPLETING-->PENDING-->COMPLETING-->IDLE
74 // If a failure happens while in IDLE, it is a noop since there is no operation to tell of the failure.
75 // If a failure happens while in WRITING, but the the write has finished successfully or with an IOExceptions,
76 // the callback's complete or respectively failed methods will be called.
77 // If a failure happens in PENDING state, then the fail method calls the pending callback and moves to IDLE state
79 // IDLE--(fail)-->IDLE
80 // IDLE-->WRITING--(fail)-->FAILED-->IDLE
81 // IDLE-->WRITING-->PENDING--(fail)-->IDLE
82 // IDLE-->WRITING-->PENDING-->COMPLETING--(fail)-->FAILED-->IDLE
84 // So a call to fail in the PENDING state will be directly handled and the state changed to IDLE
85 // A call to fail in the WRITING or COMPLETING states will just set the state to FAILED and the failure will be
86 // handled with the write or completeWrite methods try to move the state from what they thought it was.
89 protected WriteFlusher(EndPoint endPoint)
95 private enum StateType
105 * Tries to update the current state to the given new state.
106 * @param previous the expected current state
107 * @param next the desired new state
108 * @return the previous state or null if the state transition failed
109 * @throws WritePendingException if currentState is WRITING and new state is WRITING (api usage error)
111 private boolean updateState(State previous,State next)
113 if (!isTransitionAllowed(previous,next))
114 throw new IllegalStateException();
116 boolean updated = _state.compareAndSet(previous, next);
118 LOG.debug("update {}:{}{}{}", this, previous, updated?"-->":"!->",next);
122 private void fail(PendingState pending)
124 State current = _state.get();
125 if (current.getType()==StateType.FAILED)
127 FailedState failed=(FailedState)current;
128 if (updateState(failed,__IDLE))
130 pending.fail(failed.getCause());
134 throw new IllegalStateException();
137 private void ignoreFail()
139 State current = _state.get();
140 while (current.getType()==StateType.FAILED)
142 if (updateState(current,__IDLE))
144 current = _state.get();
148 private boolean isTransitionAllowed(State currentState, State newState)
150 Set<StateType> allowedNewStateTypes = __stateTransitions.get(currentState.getType());
151 if (!allowedNewStateTypes.contains(newState.getType()))
153 LOG.warn("{}: {} -> {} not allowed", this, currentState, newState);
160 * State represents a State of WriteFlusher.
162 private static class State
164 private final StateType _type;
166 private State(StateType stateType)
171 public StateType getType()
177 public String toString()
179 return String.format("%s", _type);
184 * In IdleState WriteFlusher is idle and accepts new writes
186 private static class IdleState extends State
190 super(StateType.IDLE);
195 * In WritingState WriteFlusher is currently writing.
197 private static class WritingState extends State
199 private WritingState()
201 super(StateType.WRITING);
206 * In FailedState no more operations are allowed. The current implementation will never recover from this state.
208 private static class FailedState extends State
210 private final Throwable _cause;
211 private FailedState(Throwable cause)
213 super(StateType.FAILED);
217 public Throwable getCause()
224 * In CompletingState WriteFlusher is flushing buffers that have not been fully written in write(). If write()
225 * didn't flush all buffers in one go, it'll switch the State to PendingState. completeWrite() will then switch to
226 * this state and try to flush the remaining buffers.
228 private static class CompletingState extends State
230 private CompletingState()
232 super(StateType.COMPLETING);
237 * In PendingState not all buffers could be written in one go. Then write() will switch to PendingState() and
238 * preserve the state by creating a new PendingState object with the given parameters.
240 private class PendingState extends State
242 private final Callback _callback;
243 private final ByteBuffer[] _buffers;
245 private PendingState(ByteBuffer[] buffers, Callback callback)
247 super(StateType.PENDING);
248 _buffers = compact(buffers);
249 _callback = callback;
252 public ByteBuffer[] getBuffers()
257 protected boolean fail(Throwable cause)
261 _callback.failed(cause);
267 protected void complete()
270 _callback.succeeded();
274 * Compacting the buffers is needed because the semantic of WriteFlusher is
275 * to write the buffers and if the caller sees that the buffer is consumed,
276 * then it can recycle it.
277 * If we do not compact, then it is possible that we store a consumed buffer,
278 * which is then recycled and refilled; when the WriteFlusher is invoked to
279 * complete the write, it will write the refilled bytes, garbling the content.
281 * @param buffers the buffers to compact
282 * @return the compacted buffers
284 private ByteBuffer[] compact(ByteBuffer[] buffers)
286 int length = buffers.length;
288 // Just one element, no need to compact
292 // How many still have content ?
294 while (consumed < length && BufferUtil.isEmpty(buffers[consumed]))
297 // All of them still have content, no need to compact
301 // None has content, return empty
302 if (consumed == length)
303 return EMPTY_BUFFERS;
305 return Arrays.copyOfRange(buffers,consumed,length);
310 * Abstract call to be implemented by specific WriteFlushers. It should schedule a call to {@link #completeWrite()}
311 * or {@link #onFail(Throwable)} when appropriate.
313 abstract protected void onIncompleteFlushed();
316 * Tries to switch state to WRITING. If successful it writes the given buffers to the EndPoint. If state transition
317 * fails it'll fail the callback.
319 * If not all buffers can be written in one go it creates a new <code>PendingState</code> object to preserve the state
320 * and then calls {@link #onIncompleteFlushed()}. The remaining buffers will be written in {@link #completeWrite()}.
322 * If all buffers have been written it calls callback.complete().
324 * @param callback the callback to call on either failed or complete
325 * @param buffers the buffers to flush to the endpoint
327 public void write(Callback callback, ByteBuffer... buffers) throws WritePendingException
330 LOG.debug("write: {} {}", this, BufferUtil.toDetailString(buffers));
332 if (!updateState(__IDLE,__WRITING))
333 throw new WritePendingException();
337 boolean flushed=_endPoint.flush(buffers);
339 LOG.debug("flushed {}", flushed);
342 for (ByteBuffer b : buffers)
344 if (!flushed||BufferUtil.hasContent(b))
346 PendingState pending=new PendingState(buffers, callback);
347 if (updateState(__WRITING,pending))
348 onIncompleteFlushed();
355 // If updateState didn't succeed, we don't care as our buffers have been written
356 if (!updateState(__WRITING,__IDLE))
359 callback.succeeded();
361 catch (IOException e)
364 LOG.debug("write exception", e);
365 if (updateState(__WRITING,__IDLE))
371 fail(new PendingState(buffers, callback));
377 * Complete a write that has not completed and that called {@link #onIncompleteFlushed()} to request a call to this
378 * method when a call to {@link EndPoint#flush(ByteBuffer...)} is likely to be able to progress.
380 * It tries to switch from PENDING to COMPLETING. If state transition fails, then it does nothing as the callback
381 * should have been already failed. That's because the only way to switch from PENDING outside this method is
382 * {@link #onFail(Throwable)} or {@link #onClose()}
384 public void completeWrite()
387 LOG.debug("completeWrite: {}", this);
389 State previous = _state.get();
391 if (previous.getType()!=StateType.PENDING)
392 return; // failure already handled.
394 PendingState pending = (PendingState)previous;
395 if (!updateState(pending,__COMPLETING))
396 return; // failure already handled.
400 ByteBuffer[] buffers = pending.getBuffers();
402 boolean flushed=_endPoint.flush(buffers);
404 LOG.debug("flushed {}", flushed);
407 for (ByteBuffer b : buffers)
409 if (!flushed || BufferUtil.hasContent(b))
411 if (updateState(__COMPLETING,pending))
412 onIncompleteFlushed();
419 // If updateState didn't succeed, we don't care as our buffers have been written
420 if (!updateState(__COMPLETING,__IDLE))
424 catch (IOException e)
427 LOG.debug("completeWrite exception", e);
428 if(updateState(__COMPLETING,__IDLE))
435 /* ------------------------------------------------------------ */
436 /** Notify the flusher of a failure
437 * @param cause The cause of the failure
438 * @return true if the flusher passed the failure to a {@link Callback} instance
440 public boolean onFail(Throwable cause)
442 // Keep trying to handle the failure until we get to IDLE or FAILED state
445 State current=_state.get();
446 switch(current.getType())
451 LOG.debug("ignored: {} {}", this, cause);
456 LOG.debug("failed: {} {}", this, cause);
458 PendingState pending = (PendingState)current;
459 if (updateState(pending,__IDLE))
460 return pending.fail(cause);
465 LOG.debug("failed: {} {}", this, cause);
467 if (updateState(current,new FailedState(cause)))
474 public void onClose()
476 if (_state.get()==__IDLE)
478 onFail(new ClosedChannelException());
483 return _state.get().getType() == StateType.IDLE;
486 public boolean isInProgress()
488 switch(_state.get().getType())
500 public String toString()
502 return String.format("WriteFlusher@%x{%s}", hashCode(), _state.get());