java.lang.Object
com.sun.xml.ws.api.pipe.Fiber
- All Implemented Interfaces:
Cancelable
,Component
,ComponentRegistry
,Runnable
User-level thread. Represents the execution of one request/response processing.
JAX-WS RI is capable of running a large number of request/response concurrently by using a relatively small number of threads. This is made possible by utilizing a
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.
Fiber can be
Just like thread, a fiber has a context class loader (CCL.) A fiber's CCL becomes the thread's CCL when it's executing the fiber. The original CCL of the thread will be restored when the thread leaves the fiber execution.
Because
Setting the
When you debug the server side, consider setting
JAX-WS RI is capable of running a large number of request/response concurrently by using a relatively small number of threads. This is made possible by utilizing a
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.
Suspend/Resume
Fiber can be
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.
Context-switch Interception
FiberContextSwitchInterceptor
allows Tube
s and Adapter
s
to perform additional processing every time a thread starts running a fiber
and stops running it.
Context ClassLoader
Just like thread, a fiber has a context class loader (CCL.) A fiber's CCL becomes the thread's CCL when it's executing the fiber. The original CCL of the thread will be restored when the thread leaves the fiber execution.
Debugging Aid
Because
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.- Author:
- Kohsuke Kawaguchi, Jitendra Kotamraju
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic interface
Callback to be invoked when aFiber
finishes execution.static interface
Deprecated. -
Field Summary
Modifier and TypeFieldDescriptionfinal Engine
static boolean
Set this boolean to true to execute fibers sequentially one by one. -
Method Summary
Modifier and TypeMethodDescriptionvoid
addInterceptor
(FiberContextSwitchInterceptor interceptor) Adds a newFiberContextSwitchInterceptor
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.Returns completion callback associated with this FiberReturns the set ofComponent
s registered with this objectGets the contextClassLoader
of this fiber.static Fiber
Gets the current fiber that's running, if set.Gets the currentPacket
associated with this fiber.<S> S
Gets the specified SPI.boolean
Returns true if the current Fiber on the current thread was started synchronously.static boolean
(ADVANCED) Returns true if the current fiber is being executed synchronously.boolean
removeInterceptor
(FiberContextSwitchInterceptor interceptor) Removes aFiberContextSwitchInterceptor
from this fiber.void
removeListener
(Fiber.Listener listener) Deprecated.void
Only to be used by Tubes that manipulate the Fiber to create alternate flowsvoid
Wakes up a suspended fiber.void
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
Wakes up a suspended fiber with an exception.void
Wakes up a suspend fiber with an exception.void
Wakes up a suspended fiber with an exception.void
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.Runs a givenTube
(and everything thereafter) synchronously.void
setCompletionCallback
(Fiber.CompletionCallback completionCallback) Updates completion callback associated with this FibersetContextClassLoader
(ClassLoader contextClassLoader) Sets the contextClassLoader
of this fiber.void
setDeliverThrowableInPacket
(boolean isDeliverThrowableInPacket) 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.toString()
-
Field Details
-
owner
-
serializeExecution
public static volatile boolean serializeExecutionSet this boolean to true to execute fibers sequentially one by one. See class javadoc.
-
-
Method Details
-
addListener
Deprecated.Adds suspend/resume callback listener- Parameters:
listener
- Listener- Since:
- 2.2.6
-
removeListener
Deprecated.Removes suspend/resume callback listener- Parameters:
listener
- Listener- Since:
- 2.2.6
-
setDeliverThrowableInPacket
public void setDeliverThrowableInPacket(boolean isDeliverThrowableInPacket) -
start
public void start(@NotNull Tube tubeline, @NotNull Packet request, @Nullable Fiber.CompletionCallback completionCallback) - Parameters:
tubeline
- The first tube of the tubeline that will act on the packet.request
- The request packet to be passed tostartPoint.processRequest()
.completionCallback
- The callback to be invoked when the processing is finished and the final response packet is available.- See Also:
-
start
public void start(@NotNull Tube tubeline, @NotNull Packet request, @Nullable Fiber.CompletionCallback completionCallback, boolean forceSync) Starts the execution of this fiber. If forceSync is true, then the fiber is started for an ostensibly async invocation, but allows for some portion of the tubeline to run sync with the calling client instance (Port/Dispatch instance). This allows tubes that enforce ordering to see requests in the order they were sent at the point the client invoked them.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()
.- Parameters:
tubeline
- The first tube of the tubeline that will act on the packet.request
- The request packet to be passed tostartPoint.processRequest()
.completionCallback
- The callback to be invoked when the processing is finished and the final response packet is available.- Since:
- 2.2.6
- See Also:
-
resume
Wakes up a suspended fiber.
If a fiber was suspended without specifying the nextTube
, then the execution will be resumed in the response processing direction, by calling theTube.processResponse(Packet)
method on the next/firstTube
in theFiber
's processing stack with the specified resume packet as the parameter.
If a fiber was suspended with specifying the nextTube
, then the execution will be resumed in the request processing direction, by calling the next tube'sTube.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 synchronizingNextAction.suspend()
and this method.- Parameters:
resumePacket
- packet used in the resumed processing
-
resume
Similar to resume(Packet) but allowing the Fiber to be resumed synchronously (in the current Thread). If you want to know when the fiber completes (not when this method returns) then add/wrap a CompletionCallback on this Fiber. For example, an asynchronous response endpoint that supports WS-ReliableMessaging including in-order message delivery may need to resume the Fiber synchronously until message order is confirmed prior to returning to asynchronous processing.- Since:
- 2.2.6
-
resume
public void resume(@NotNull 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.- Since:
- 2.2.6
-
resumeAndReturn
Wakes up a suspended fiber and begins response processing.- Since:
- 2.2.6
-
resume
Wakes up a suspended fiber with an exception.
The execution of the suspended fiber will be resumed in the response processing direction, by calling theTube.processException(Throwable)
method on the next/firstTube
in theFiber
'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 synchronizingNextAction.suspend()
and this method.- Parameters:
throwable
- exception that is used in the resumed processing
-
resume
Wakes up a suspended fiber with an exception.
The execution of the suspended fiber will be resumed in the response processing direction, by calling theTube.processException(Throwable)
method on the next/firstTube
in theFiber
'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 synchronizingNextAction.suspend()
and this method.- Parameters:
throwable
- exception that is used in the resumed processingpacket
- Packet that will be visible on the Fiber after the resume- Since:
- 2.2.8
-
resume
Wakes up a suspend fiber with an exception. If forceSync is true, then the suspended fiber will resume with synchronous processing on the current thread. This will continue until some Tube indicates that it is safe to switch to asynchronous processing.- Parameters:
error
- exception that is used in the resumed processingforceSync
- if processing begins synchronously- Since:
- 2.2.6
-
resume
Wakes up a suspend fiber with an exception. If forceSync is true, then the suspended fiber will resume with synchronous processing on the current thread. This will continue until some Tube indicates that it is safe to switch to asynchronous processing.- Parameters:
error
- exception that is used in the resumed processingpacket
- Packet that will be visible on the Fiber after the resumeforceSync
- if processing begins synchronously- Since:
- 2.2.8
-
cancel
public void cancel(boolean mayInterrupt) Marks this Fiber as cancelled. A cancelled Fiber will never invoke its completion callback- Specified by:
cancel
in interfaceCancelable
- Parameters:
mayInterrupt
- if cancel should useThread.interrupt()
- Since:
- 2.2.6
- See Also:
-
addInterceptor
Adds a newFiberContextSwitchInterceptor
to this fiber.
The newly installed fiber will take effect immediately after the current tube returns from itsTube.processRequest(Packet)
orTube.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:
- X.processRequest()
- interceptor gets installed
- interceptor.execute() is invoked
- Y.processRequest()
-
removeInterceptor
Removes aFiberContextSwitchInterceptor
from this fiber.
The removal of the interceptor takes effect immediately after the current tube returns from itsTube.processRequest(Packet)
orTube.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:
- Y.processResponse() (notice that this happens with interceptor.execute() in the callstack)
- interceptor gets uninstalled
- interceptor.execute() returns
- X.processResponse()
- Returns:
- true if the specified interceptor was removed. False if the specified interceptor was not registered with this fiber to begin with.
-
getContextClassLoader
Gets the contextClassLoader
of this fiber. -
setContextClassLoader
Sets the contextClassLoader
of this fiber. -
run
Deprecated.DO NOT CALL THIS METHOD. This is an implementation detail ofFiber
. -
runSync
Runs a givenTube
(and everything thereafter) synchronously.
This method blocks and returns only when all the successiveTube
s complete their request/response processing. This method can be used if aTube
needs to fallback to synchronous processing.
Example:
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 } }- Parameters:
tubeline
- The first tube of the tubeline that will act on the packet.request
- The request packet to be passed tostartPoint.processRequest()
.- Returns:
- The response packet to the
request
. - See Also:
-
resetCont
Only to be used by Tubes that manipulate the Fiber to create alternate flows- Since:
- 2.2.6
-
toString
-
getPacket
Gets the currentPacket
associated with this fiber.
This method returns null if no packet has been associated with the fiber yet. -
getCompletionCallback
Returns completion callback associated with this Fiber- Returns:
- Completion callback
- Since:
- 2.2.6
-
setCompletionCallback
Updates completion callback associated with this Fiber- Parameters:
completionCallback
- Completion callback- Since:
- 2.2.6
-
isSynchronous
public static boolean isSynchronous()(ADVANCED) Returns true if the current fiber is being executed synchronously.
Fiber may run synchronously for various reasons. Perhaps this is on client side and application has invoked a synchronous method call. Perhaps this is on server side and we have deployed on a synchronous transport (like servlet.)
When a fiber is run synchronously (IOW byrunSync(Tube, Packet)
), further invocations torunSync(Tube, Packet)
can be done without degrading the performance.
So this value can be used as a further optimization hint for advancedTube
s to choose the best strategy to invoke the nextTube
. For example, a tube may want to install aFiberContextSwitchInterceptor
if running async, yet it might find it faster to dorunSync(Tube, Packet)
if it's already running synchronously. -
isStartedSync
public boolean isStartedSync()Returns true if the current Fiber on the current thread was started synchronously. Note, this is not strictly the same as being synchronous because the assumption is that the Fiber will ultimately be dispatched asynchronously, possibly have a completion callback associated with it, etc. Note, the 'startedSync' flag is cleared once the current Fiber is converted to running asynchronously.- Since:
- 2.2.6
-
current
Gets the current fiber that's running.
This works likeThread.currentThread()
. This method only works when invoked fromTube
. -
getCurrentIfSet
Gets the current fiber that's running, if set. -
getSPI
Description copied from interface:Component
Gets the specified SPI.This method works as a kind of directory service for SPIs, allowing various components to define private contract and talk to each other.
-
getComponents
Description copied from interface:ComponentRegistry
Returns the set ofComponent
s registered with this object- Specified by:
getComponents
in interfaceComponentRegistry
- Returns:
- set of registered components
-
NextAction.suspend(Runnable)