public final class Fiber extends Object implements Runnable, Cancelable, ComponentRegistry
Fiber
— a user-level thread that gets created for each request/response
processing.
A fiber remembers where in the pipeline the processing is at, what needs to be
executed on the way out (when processing response), and other additional information
specific to the execution of a particular request/response.
suspended
by a Tube
.
When a fiber is suspended, it will be kept on the side until it is
resumed
. This allows threads to go execute
other runnable fibers, allowing efficient utilization of smaller number of
threads.
FiberContextSwitchInterceptor
allows Tube
s and Adapter
s
to perform additional processing every time a thread starts running a fiber
and stops running it.
Fiber
doesn't keep much in the call stack, and instead use
conts
to store the continuation, debugging fiber related activities
could be harder.
Setting the LOGGER
for FINE would give you basic start/stop/resume/suspend
level logging. Using FINER would cause more detailed logging, which includes
what tubes are executed in what order and how they behaved.
When you debug the server side, consider setting serializeExecution
to true, so that execution of fibers are serialized. Debugging a server
with more than one running threads is very tricky, and this switch will
prevent that. This can be also enabled by setting the system property on.
See the source code.Modifier and Type | Class and Description |
---|---|
static interface |
Fiber.CompletionCallback
Callback to be invoked when a
Fiber finishs execution. |
static interface |
Fiber.Listener
Deprecated.
|
Modifier and Type | Field and Description |
---|---|
Engine |
owner |
static boolean |
serializeExecution
Set this boolean to true to execute fibers sequentially one by one.
|
Modifier and Type | Method and Description |
---|---|
void |
addInterceptor(FiberContextSwitchInterceptor interceptor)
Adds a new
FiberContextSwitchInterceptor to this fiber. |
void |
addListener(Fiber.Listener listener)
Deprecated.
|
void |
cancel(boolean mayInterrupt)
Marks this Fiber as cancelled.
|
static Fiber |
current()
Gets the current fiber that's running.
|
Fiber.CompletionCallback |
getCompletionCallback()
Returns completion callback associated with this Fiber
|
Set<Component> |
getComponents()
Returns the set of
Component s registered with this object |
ClassLoader |
getContextClassLoader()
Gets the context
ClassLoader of this fiber. |
static Fiber |
getCurrentIfSet()
Gets the current fiber that's running, if set.
|
Packet |
getPacket()
Gets the current
Packet associated with this fiber. |
<S> S |
getSPI(Class<S> spiType)
Gets the specified SPI.
|
boolean |
isStartedSync()
Returns true if the current Fiber on the current thread was started
synchronously.
|
static boolean |
isSynchronous()
(ADVANCED) Returns true if the current fiber is being executed synchronously.
|
boolean |
removeInterceptor(FiberContextSwitchInterceptor interceptor)
Removes a
FiberContextSwitchInterceptor from this fiber. |
void |
removeListener(Fiber.Listener listener)
Deprecated.
|
void |
resetCont(Tube[] conts,
int contsSize)
Only to be used by Tubes that manipulate the Fiber to create alternate flows
|
void |
resume(Packet resumePacket)
Wakes up a suspended fiber.
|
void |
resume(Packet resumePacket,
boolean forceSync)
Similar to resume(Packet) but allowing the Fiber to be resumed
synchronously (in the current Thread).
|
void |
resume(Packet resumePacket,
boolean forceSync,
Fiber.CompletionCallback callback)
Similar to resume(Packet, boolean) but allowing the Fiber to be resumed
and at the same time atomically assign a new CompletionCallback to it.
|
void |
resume(Throwable throwable)
Wakes up a suspended fiber with an exception.
|
void |
resume(Throwable error,
boolean forceSync)
Wakes up a suspend fiber with an exception.
|
void |
resumeAndReturn(Packet resumePacket,
boolean forceSync)
Wakes up a suspended fiber and begins response processing.
|
void |
run()
Deprecated.
|
Packet |
runSync(Tube tubeline,
Packet request)
Runs a given
Tube (and everything thereafter) synchronously. |
void |
setCompletionCallback(Fiber.CompletionCallback completionCallback)
Updates completion callback associated with this Fiber
|
ClassLoader |
setContextClassLoader(ClassLoader contextClassLoader)
Sets the context
ClassLoader of this fiber. |
void |
start(Tube tubeline,
Packet request,
Fiber.CompletionCallback completionCallback)
Starts the execution of this fiber asynchronously.
|
void |
start(Tube tubeline,
Packet request,
Fiber.CompletionCallback completionCallback,
boolean forceSync)
Starts the execution of this fiber.
|
String |
toString() |
public final Engine owner
public static volatile boolean serializeExecution
Fiber(Engine engine)
public void addListener(Fiber.Listener listener)
listener
- Listenerpublic void removeListener(Fiber.Listener listener)
listener
- Listenerpublic void start(@NotNull Tube tubeline, @NotNull Packet request, @Nullable Fiber.CompletionCallback completionCallback)
Thread.start()
.tubeline
- The first tube of the tubeline that will act on the packet.request
- The request packet to be passed to startPoint.processRequest().completionCallback
- The callback to be invoked when the processing is finished and the
final response packet is available.runSync(Tube, Packet)
public void start(@NotNull Tube tubeline, @NotNull Packet request, @Nullable Fiber.CompletionCallback completionCallback, boolean forceSync)
The forceSync parameter will be true only when the caller (e.g. AsyncInvoker or SEIStub) knows one or more tubes need to enforce ordering and thus need to run sync with the client. Such tubes can return NextAction.INVOKE_ASYNC to indicate that the next tube in the tubeline should be invoked async to the current thread.
This method works like Thread.start()
.
tubeline
- The first tube of the tubeline that will act on the packet.request
- The request packet to be passed to startPoint.processRequest().completionCallback
- The callback to be invoked when the processing is finished and the
final response packet is available.start(Tube,Packet,CompletionCallback)
,
runSync(Tube,Packet)
public void resume(@NotNull Packet resumePacket)
Tube
,
then the execution will be resumed in the response processing direction,
by calling the Tube.processResponse(Packet)
method on the next/first
Tube
in the Fiber
's processing stack with the specified resume
packet as the parameter.
If a fiber was suspended with specifying the next Tube
,
then the execution will be resumed in the request processing direction,
by calling the next tube's Tube.processRequest(Packet)
method with the
specified resume packet as the parameter.
This method is implemented in a race-free way. Another thread can invoke
this method even before this fiber goes into the suspension mode. So the caller
need not worry about synchronizing NextAction.suspend()
and this method.resumePacket
- packet used in the resumed processingpublic void resume(@NotNull Packet resumePacket, boolean forceSync)
public void resume(@NotNull Packet resumePacket, boolean forceSync, Fiber.CompletionCallback callback)
public void resumeAndReturn(@NotNull Packet resumePacket, boolean forceSync)
public void resume(@NotNull Throwable throwable)
Tube.processException(Throwable)
method
on the next/first Tube
in the Fiber
's processing stack with
the specified exception as the parameter.
This method is implemented in a race-free way. Another thread can invoke
this method even before this fiber goes into the suspension mode. So the caller
need not worry about synchronizing NextAction.suspend()
and this method.throwable
- exception that is used in the resumed processingpublic void resume(@NotNull Throwable error, boolean forceSync)
error
- exception that is used in the resumed processingforceSync
- if processing begins synchronouslypublic void cancel(boolean mayInterrupt)
cancel
in interface Cancelable
mayInterrupt
- if cancel should use Thread.interrupt()
Future.cancel
public void addInterceptor(@NotNull FiberContextSwitchInterceptor interceptor)
FiberContextSwitchInterceptor
to this fiber.
The newly installed fiber will take effect immediately after the current
tube returns from its Tube.processRequest(Packet)
or
Tube.processResponse(Packet)
, before the next tube begins processing.
So when the tubeline consists of X and Y, and when X installs an interceptor,
the order of execution will be as follows:
public boolean removeInterceptor(@NotNull FiberContextSwitchInterceptor interceptor)
FiberContextSwitchInterceptor
from this fiber.
The removal of the interceptor takes effect immediately after the current
tube returns from its Tube.processRequest(Packet)
or
Tube.processResponse(Packet)
, before the next tube begins processing.
So when the tubeline consists of X and Y, and when Y uninstalls an interceptor
on the way out, then the order of execution will be as follows:
@Nullable public ClassLoader getContextClassLoader()
ClassLoader
of this fiber.public ClassLoader setContextClassLoader(@Nullable ClassLoader contextClassLoader)
ClassLoader
of this fiber.@Deprecated public void run()
Fiber
.@NotNull public Packet runSync(@NotNull Tube tubeline, @NotNull Packet request)
Tube
(and everything thereafter) synchronously.
This method blocks and returns only when all the successive Tube
s
complete their request/response processing. This method can be used
if a Tube
needs to fallback to synchronous processing.
class FooTube extends AbstractFilterTubeImpl
{
NextAction processRequest(Packet request) {
// run everything synchronously and return with the response packet
return doReturnWith(Fiber.current().runSync(next,request));
}
NextAction processResponse(Packet response) {
// never be invoked
}
}
tubeline
- The first tube of the tubeline that will act on the packet.request
- The request packet to be passed to startPoint.processRequest().start(Tube, Packet, CompletionCallback)
public void resetCont(Tube[] conts, int contsSize)
@Nullable public Packet getPacket()
Packet
associated with this fiber.
This method returns null if no packet has been associated with the fiber yet.public Fiber.CompletionCallback getCompletionCallback()
public void setCompletionCallback(Fiber.CompletionCallback completionCallback)
completionCallback
- Completion callbackpublic static boolean isSynchronous()
runSync(Tube, Packet)
),
further invocations to runSync(Tube, Packet)
can be done
without degrading the performance.
So this value can be used as a further optimization hint for
advanced Tube
s to choose the best strategy to invoke
the next Tube
. For example, a tube may want to install
a FiberContextSwitchInterceptor
if running async, yet
it might find it faster to do runSync(Tube, Packet)
if it's already running synchronously.public boolean isStartedSync()
@NotNull public static Fiber current()
Thread.currentThread()
.
This method only works when invoked from Tube
.public static Fiber getCurrentIfSet()
public <S> S getSPI(Class<S> spiType)
Component
This method works as a kind of directory service for SPIs, allowing various components to define private contract and talk to each other.
public Set<Component> getComponents()
ComponentRegistry
Component
s registered with this objectgetComponents
in interface ComponentRegistry
Copyright (c) 1997-2012 Oracle and/or its affiliates. All rights reserved.