EmbeddedChannel
public final class EmbeddedChannel : Channel
EmbeddedChannel
is a Channel
implementation that does neither any
actual IO nor has a proper eventing mechanism. The prime use-case for
EmbeddedChannel
is in unit tests when you want to feed the inbound events
and check the outbound events manually.
Please remember to call finish()
when you are no longer using this
EmbeddedChannel
.
To feed events through an EmbeddedChannel
‘s ChannelPipeline
use
EmbeddedChannel.writeInbound
which accepts data of any type. It will then
forward that data through the ChannelPipeline
and the subsequent
ChannelInboundHandler
will receive it through the usual channelRead
event. The user is responsible for making sure the first
ChannelInboundHandler
expects data of that type.
EmbeddedChannel
automatically collects arriving outbound data and makes it
available one-by-one through readOutbound
.
Note
EmbeddedChannel
is currently only compatible with
EmbeddedEventLoop
s and cannot be used with SelectableEventLoop
s from
for example MultiThreadedEventLoopGroup
.
Warning
Unlike otherChannel
s, EmbeddedChannel
is not thread-safe. This
is because it is intended to be run in the thread that instantiated it. Users are
responsible for ensuring they never call into an EmbeddedChannel
in an
unsynchronized fashion. EmbeddedEventLoop
s notes also apply as
EmbeddedChannel
uses an EmbeddedEventLoop
as its EventLoop
.
-
LeftOverState
represents any left-over inbound, outbound, and pending outbound events that hit theEmbeddedChannel
and were not consumed whenfinish
was called on theEmbeddedChannel
.
See moreEmbeddedChannel
is most useful in testing and usually in unit tests, you want to consume all inbound and outbound data to verify they are what you expect. Therefore, when youfinish
anEmbeddedChannel
it will return if it’s either.clean
(no left overs) or that it has.leftOvers
.Declaration
Swift
public enum LeftOverState
-
BufferState
represents the state of either the inbound, or the outboundEmbeddedChannel
buffer. These buffers contain data that travelled theChannelPipeline
all the way.If the last
See moreChannelHandler
explicitly (by callingfireChannelRead
) or implicitly (by not implementingchannelRead
) sends inbound data into the end of theEmbeddedChannel
, it will be held in theEmbeddedChannel
‘s inbound buffer. Similarly forwrite
on the outbound side. The state of the respective buffer will be returned fromwriteInbound
/writeOutbound
as aBufferState
.Declaration
Swift
public enum BufferState
-
See moreWrongTypeError
is throws if you usereadInbound
orreadOutbound
and request a certain type but the first item in the respective buffer is of a different type.Declaration
Swift
public struct WrongTypeError : Error, Equatable
-
Returns
true
if theEmbeddedChannel
is ‘active’.An active
EmbeddedChannel
can be closed by callingclose
orfinish
on theEmbeddedChannel
.Note
AnEmbeddedChannel
starts inactive and can be activated, for example by callingconnect
.Declaration
Swift
public var isActive: Bool { get }
-
Declaration
Swift
public var closeFuture: EventLoopFuture<Void> { get }
-
Declaration
Swift
public var _channelCore: ChannelCore { get }
-
See
Channel.pipeline
Declaration
Swift
public var pipeline: ChannelPipeline { get }
-
Declaration
Swift
public var isWritable: Bool
-
Synchronously closes the
EmbeddedChannel
.Errors in the
EmbeddedChannel
can be consumed usingthrowIfErrorCaught
.Declaration
Swift
public func finish(acceptAlreadyClosed: Bool) throws -> LeftOverState
Parameters
acceptAlreadyClosed
Whether
finish
should throw if theEmbeddedChannel
has been previouslyclose
d.Return Value
The
LeftOverState
of theEmbeddedChannel
. If all the inbound and outbound events have been consumed (usingreadInbound
/readOutbound
) and there are no pending outbound events (unflushed writes) this will be.clean
. If there are any unconsumed inbound, outbound, or pending outbound events, theEmbeddedChannel
will returns those as.leftOvers(inbound:outbound:pendingOutbound:)
. -
Synchronously closes the
EmbeddedChannel
.This method will throw if the
Channel
hit any unconsumed errors or if theclose
fails. Errors in theEmbeddedChannel
can be consumed usingthrowIfErrorCaught
.Declaration
Swift
public func finish() throws -> LeftOverState
Return Value
The
LeftOverState
of theEmbeddedChannel
. If all the inbound and outbound events have been consumed (usingreadInbound
/readOutbound
) and there are no pending outbound events (unflushed writes) this will be.clean
. If there are any unconsumed inbound, outbound, or pending outbound events, theEmbeddedChannel
will returns those as.leftOvers(inbound:outbound:pendingOutbound:)
. -
Declaration
Swift
public var allocator: ByteBufferAllocator
-
See
Channel.eventLoop
Declaration
Swift
public var eventLoop: EventLoop { get }
-
Returns the
EmbeddedEventLoop
that thisEmbeddedChannel
uses. This will return the same instance asEmbeddedChannel.eventLoop
but as the concreteEmbeddedEventLoop
rather than asEventLoop
existential.Declaration
Swift
public var embeddedEventLoop: EmbeddedEventLoop
-
Declaration
Swift
public var localAddress: SocketAddress?
-
Declaration
Swift
public var remoteAddress: SocketAddress?
-
nil
becauseEmbeddedChannel
s don’t have parents.Declaration
Swift
public let parent: Channel?
-
If available, this method reads one element of type
T
out of theEmbeddedChannel
‘s outbound buffer. If the first element was of a different type than requested,EmbeddedChannel.WrongTypeError
will be thrown, if there are no elements in the outbound buffer,nil
will be returned.Data hits the
EmbeddedChannel
’s outbound buffer when data was written usingwrite
, thenflush
ed, and then travelled theChannelPipeline
all the way too the front. For data to hit the outbound buffer, the very firstChannelHandler
must have written and flushed it either explicitly (by callingChannelHandlerContext.write
andflush
) or implicitly by not implementingwrite
/flush
.Note
Outbound events travel theChannelPipeline
back to front.Note
EmbeddedChannel.writeOutbound
willwrite
data through theChannelPipeline
, starting with lastChannelHandler
.Declaration
Swift
@inlinable public func readOutbound<T>(as type: T.Type = T.self) throws -> T?
-
If available, this method reads one element of type
T
out of theEmbeddedChannel
‘s inbound buffer. If the first element was of a different type than requested,EmbeddedChannel.WrongTypeError
will be thrown, if there are no elements in the outbound buffer,nil
will be returned.Data hits the
EmbeddedChannel
’s inbound buffer when data was send through the pipeline usingfireChannelRead
and then travelled theChannelPipeline
all the way too the back. For data to hit the inbound buffer, the lastChannelHandler
must have send the event either explicitly (by callingChannelHandlerContext.fireChannelRead
) or implicitly by not implementingchannelRead
.Declaration
Swift
@inlinable public func readInbound<T>(as type: T.Type = T.self) throws -> T?
-
Undocumented
Declaration
Swift
@discardableResult @inlinable public func writeInbound<T>(_ data: T) throws -> BufferState
-
Undocumented
Declaration
Swift
@discardableResult @inlinable public func writeOutbound<T>(_ data: T) throws -> BufferState
-
This method will throw the error that is stored in the
EmbeddedChannel
if any.The
EmbeddedChannel
will store an error some error travels theChannelPipeline
all the way past its end.Declaration
Swift
public func throwIfErrorCaught() throws
-
Create a new instance.
During creation it will automatically also register itself on the
EmbeddedEventLoop
.Declaration
Swift
public init(handler: ChannelHandler? = nil, loop: EmbeddedEventLoop = EmbeddedEventLoop())
Parameters
handler
The
ChannelHandler
to add to theChannelPipeline
before register ornil
if none should be added.loop
The
EmbeddedEventLoop
to use. -
See
Channel.setOption
Declaration
Swift
public func setOption<Option>(_ option: Option, value: Option.Value) -> EventLoopFuture<Void> where Option : ChannelOption
-
See
Channel.getOption
Declaration
Swift
public func getOption<Option>(_ option: Option) -> EventLoopFuture<Option.Value> where Option : ChannelOption
-
Fires the (outbound)
bind
event through theChannelPipeline
. If the event hits theEmbeddedChannel
which happens when it travels theChannelPipeline
all the way to the front, this will also set theEmbeddedChannel
‘slocalAddress
.Declaration
Swift
public func bind(to address: SocketAddress, promise: EventLoopPromise<Void>?)
Parameters
address
The address to fake-bind to.
promise
The
EventLoopPromise
which will be fulfilled when the fake-bind operation has been done. -
Fires the (outbound)
connect
event through theChannelPipeline
. If the event hits theEmbeddedChannel
which happens when it travels theChannelPipeline
all the way to the front, this will also set theEmbeddedChannel
‘sremoteAddress
.Declaration
Swift
public func connect(to address: SocketAddress, promise: EventLoopPromise<Void>?)
Parameters
address
The address to fake-bind to.
promise
The
EventLoopPromise
which will be fulfilled when the fake-bind operation has been done.