Defines an AMQP Protocol Engine interface that should be used to implement an AMQP Engine. More...
Public Member Functions | |
| IConnection | Start () |
| Starts the engine and returns the Connection instance that is bound to this Engine. A non-started Engine will not allow ingestion of any inbound data and a Connection linked to the engine that was obtained from the engine cannot produce any outbound data. | |
| IEngine | Shutdown () |
| Shutdown the engine preventing any future outbound or inbound processing. | |
| EngineStateException | EngineFailed (Exception cause) |
| Transition the Engine to a failed state if not already closed or closing. | |
| IEngine | Ingest (IProtonBuffer input) |
| Provide data input for this Engine from some external source. If the engine is not writable when this method is called an EngineNotWritableException will be thrown unless the reason for the not writable state is due to engine failure or the engine already having been shut down in which case the appropriate EngineStateException will be thrown to indicate the reason. | |
| IEngine | Ingest (byte[] input) |
| Provide data input for this Engine from some external source. If the engine is not writable when this method is called an EngineNotWritableException will be thrown unless the reason for the not writable state is due to engine failure or the engine already having been shut down in which case the appropriate EngineStateException will be thrown to indicate the reason. | |
| long | Tick (long current) |
| Prompt the engine to perform idle-timeout/heartbeat handling, and return an absolute deadline in milliseconds that tick must again be called by/at, based on the provided current time in milliseconds, to ensure the periodic work is carried out as necessary. It is an error to call this method if the connection has not been opened. A returned deadline of 0 indicates there is no periodic work necessitating tick be called, e.g. because neither peer has defined an idle-timeout value. The provided milliseconds time values should be derived from a monotonic source such as a system tick counter to prevent wall clock changes leading to erroneous behavior. Note that for some monotonic time sources deadline could be a different sign than the originally given value, and so (if non-zero) the returned deadline should have the current time originally provided subtracted from it in order to establish a relative time delay to the next deadline. | |
| IEngine | TickAuto (TaskFactory taskFactory) |
| Allows the engine to manage idle timeout processing by providing it the single threaded task scheduler where all transport work is done which ensures singled threaded access while removing the need for the client library or server application to manage calls to the tick processing methods. | |
| IEngine | OutputHandler (Action< IProtonBuffer > handler) |
| Sets a Action instance that will be notified when data from the engine is ready to be written to some output sink (socket etc). In the event of an error writing the data the handler should throw an error or if performed asynchronously the Engine should be marked failed via a call to the engine failed API. | |
| IEngine | OutputHandler (Action< IProtonBuffer, Action > handler) |
| Sets a Action instance that will be notified when data from the engine is ready to be written to some output sink (socket etc). The Action value provided to the handler (if non-null) should be invoked once the I/O operation has completely successfully. In the event of an error writing the data the handler should throw an error or if performed asynchronously the Engine should be marked failed via a call to the engine failed API. | |
| IEngine | ErrorHandler (Action< IEngine > handler) |
| Sets a handler instance that will be notified when the engine encounters a fatal error. | |
| IEngine | ShutdownHandler (Action< IEngine > handler) |
| Sets a handler instance that will be notified when the engine is shut down via a call to the engine shutdown method. | |
Properties | |
| bool | IsRunning [get] |
| Checks if the engine is in the running state and has not failed or been shutdown yet. Will return false until start is called on the engine. | |
| bool | IsWritable [get] |
| Returns true if the engine is accepting input from the ingestion entry points. | |
| bool | IsShutdown [get] |
| Checks if the engine has been shutdown which is a terminal state after which no future engine state changes can occur. | |
| bool | IsFailed [get] |
| Checks if the engine has entered a failed state either by a call to the engine failed method or by an exception having been thrown and caught. An engine that reports failed will stop after a call to shutdown. | |
| Exception | FailureCause [get] |
| Provides an Exception that has information regarding the cause of an engine entering the failed state. | |
| EngineState | EngineState [get] |
| Provides the current engine operating state. | |
| IEngineConfiguration | Configuration [get] |
| Provides access to the configuration object associated with this engine. | |
| IEnginePipeline | Pipeline [get] |
| Provides access to the engine pipeline instance associated with this engine. | |
| IEngineSaslDriver | SaslDriver [get] |
| Provides access to the SASL driver that is assigned to this engine. | |
| IConnection | Connection [get] |
| Gets the Connection instance that is associated with this Engine instance. It is valid for an engine implementation to not return a Connection instance prior to the engine having been started although it is recommended that one be available immediately to prevent confusion. | |
Detailed Description
Defines an AMQP Protocol Engine interface that should be used to implement an AMQP Engine.
Member Function Documentation
◆ EngineFailed()
| EngineStateException Apache.Qpid.Proton.Engine.IEngine.EngineFailed | ( | Exception | cause | ) |
Transition the Engine to a failed state if not already closed or closing.
If called when the engine has not failed the engine will be transitioned to the failed state and the method will return an appropriate EngineFailedException that wraps the given cause. If called after the engine was shutdown the method returns an EngineShutdownException indicating that the engine was already shutdown. Repeated calls to this method while the engine is in the failed state must not alter the original failure error or elicit new engine failed event notifications.
- Parameters
-
cause The exception that led to the Engine being failed
- Returns
- The exception that caused the engine to be transitioned to the failed state
Implemented in Apache.Qpid.Proton.Engine.Implementation.ProtonEngine.
◆ ErrorHandler()
Sets a handler instance that will be notified when the engine encounters a fatal error.
- Parameters
-
handler The handler that will be invoked on an engine error state
- Returns
- This engine instance
- Exceptions
-
EngineStateException If the engine has failed or was shutdown
Implemented in Apache.Qpid.Proton.Engine.Implementation.ProtonEngine.
◆ Ingest() [1/2]
|
inline |
Provide data input for this Engine from some external source. If the engine is not writable when this method is called an EngineNotWritableException will be thrown unless the reason for the not writable state is due to engine failure or the engine already having been shut down in which case the appropriate EngineStateException will be thrown to indicate the reason.
- Parameters
-
input The binary data to ingest into the engine
- Returns
- This Engine instance
- Exceptions
-
EngineNotWritableException If the engine is not currently accepting input EngineStateException If the engine state is already failed or shutdown
◆ Ingest() [2/2]
| IEngine Apache.Qpid.Proton.Engine.IEngine.Ingest | ( | IProtonBuffer | input | ) |
Provide data input for this Engine from some external source. If the engine is not writable when this method is called an EngineNotWritableException will be thrown unless the reason for the not writable state is due to engine failure or the engine already having been shut down in which case the appropriate EngineStateException will be thrown to indicate the reason.
- Parameters
-
input The binary data to ingest into the engine
- Returns
- This Engine instance
- Exceptions
-
EngineNotWritableException If the engine is not currently accepting input EngineStateException If the engine state is already failed or shutdown
Implemented in Apache.Qpid.Proton.Engine.Implementation.ProtonEngine.
◆ OutputHandler() [1/2]
|
inline |
Sets a Action instance that will be notified when data from the engine is ready to be written to some output sink (socket etc). In the event of an error writing the data the handler should throw an error or if performed asynchronously the Engine should be marked failed via a call to the engine failed API.
This method allows for a handler to be registered that doesn't not need to invoke an output complete handler when done writing but does assume that any writes are complete once the handler returns. If the provided handler does any sort of queuing of writes or otherwise does not immediately complete this could lead to out of memory or other errors as the engine will not be able to apply any write backpressure,
- Parameters
-
handler The delegate that will be invoked when engine output is available
- Returns
- This engine instance
- Exceptions
-
EngineStateException If the engine has failed or was shutdown
◆ OutputHandler() [2/2]
| IEngine Apache.Qpid.Proton.Engine.IEngine.OutputHandler | ( | Action< IProtonBuffer, Action > | handler | ) |
Sets a Action instance that will be notified when data from the engine is ready to be written to some output sink (socket etc). The Action value provided to the handler (if non-null) should be invoked once the I/O operation has completely successfully. In the event of an error writing the data the handler should throw an error or if performed asynchronously the Engine should be marked failed via a call to the engine failed API.
- Parameters
-
handler The delegate that will be invoked when engine output is available
- Returns
- This engine instance
- Exceptions
-
EngineStateException If the engine has failed or was shutdown
Implemented in Apache.Qpid.Proton.Engine.Implementation.ProtonEngine.
◆ Shutdown()
| IEngine Apache.Qpid.Proton.Engine.IEngine.Shutdown | ( | ) |
Shutdown the engine preventing any future outbound or inbound processing.
When the engine is shut down any resources, Connection, Session or Link instances that have an engine shutdown event handler registered will be notified and should react by locally closing that resource if they wish to ensure that the resource's local close event handler gets signaled if that resource is not already locally closed.
- Returns
- This Engine instance
Implemented in Apache.Qpid.Proton.Engine.Implementation.ProtonEngine.
◆ ShutdownHandler()
Sets a handler instance that will be notified when the engine is shut down via a call to the engine shutdown method.
- Parameters
-
handler The handler that will be signalled on engine shutdown
- Returns
- This engine instance
- Exceptions
-
EngineStateException If the engine has failed or was shutdown
Implemented in Apache.Qpid.Proton.Engine.Implementation.ProtonEngine.
◆ Start()
| IConnection Apache.Qpid.Proton.Engine.IEngine.Start | ( | ) |
Starts the engine and returns the Connection instance that is bound to this Engine. A non-started Engine will not allow ingestion of any inbound data and a Connection linked to the engine that was obtained from the engine cannot produce any outbound data.
- Returns
- The Connection that is linked to the engine instance
- Exceptions
-
EngineStateException If the engine state is already failed or shutdown
Implemented in Apache.Qpid.Proton.Engine.Implementation.ProtonEngine.
◆ Tick()
| long Apache.Qpid.Proton.Engine.IEngine.Tick | ( | long | current | ) |
Prompt the engine to perform idle-timeout/heartbeat handling, and return an absolute deadline in milliseconds that tick must again be called by/at, based on the provided current time in milliseconds, to ensure the periodic work is carried out as necessary. It is an error to call this method if the connection has not been opened. A returned deadline of 0 indicates there is no periodic work necessitating tick be called, e.g. because neither peer has defined an idle-timeout value. The provided milliseconds time values should be derived from a monotonic source such as a system tick counter to prevent wall clock changes leading to erroneous behavior. Note that for some monotonic time sources deadline could be a different sign than the originally given value, and so (if non-zero) the returned deadline should have the current time originally provided subtracted from it in order to establish a relative time delay to the next deadline.
- Parameters
-
current The current system tick count
- Returns
- the absolute deadline in milliseconds to next call tick by/at, or 0 if there is none
- Exceptions
-
InvalidOperationException If the engine has already been set to auto tick EngineStateException If the engine has failed or was shutdown
Implemented in Apache.Qpid.Proton.Engine.Implementation.ProtonEngine.
◆ TickAuto()
| IEngine Apache.Qpid.Proton.Engine.IEngine.TickAuto | ( | TaskFactory | taskFactory | ) |
Allows the engine to manage idle timeout processing by providing it the single threaded task scheduler where all transport work is done which ensures singled threaded access while removing the need for the client library or server application to manage calls to the tick processing methods.
- Parameters
-
taskFactory The single threaded task factory where are engine work is queued
- Returns
- This engine instance
- Exceptions
-
EngineStateException If the engine has failed or was shutdown
Implemented in Apache.Qpid.Proton.Engine.Implementation.ProtonEngine.
Property Documentation
◆ Configuration
|
get |
Provides access to the configuration object associated with this engine.
Implemented in Apache.Qpid.Proton.Engine.Implementation.ProtonEngine.
◆ Connection
|
get |
Gets the Connection instance that is associated with this Engine instance. It is valid for an engine implementation to not return a Connection instance prior to the engine having been started although it is recommended that one be available immediately to prevent confusion.
Implemented in Apache.Qpid.Proton.Engine.Implementation.ProtonEngine.
◆ EngineState
|
get |
Provides the current engine operating state.
Implemented in Apache.Qpid.Proton.Engine.Implementation.ProtonEngine.
◆ FailureCause
|
get |
Provides an Exception that has information regarding the cause of an engine entering the failed state.
Implemented in Apache.Qpid.Proton.Engine.Implementation.ProtonEngine.
◆ IsFailed
|
get |
Checks if the engine has entered a failed state either by a call to the engine failed method or by an exception having been thrown and caught. An engine that reports failed will stop after a call to shutdown.
- Returns
- true if the engine is in a failed state
Implemented in Apache.Qpid.Proton.Engine.Implementation.ProtonEngine.
◆ IsRunning
|
get |
Checks if the engine is in the running state and has not failed or been shutdown yet. Will return false until start is called on the engine.
- Returns
- true if the engine is currently running.
Implemented in Apache.Qpid.Proton.Engine.Implementation.ProtonEngine.
◆ IsShutdown
|
get |
Checks if the engine has been shutdown which is a terminal state after which no future engine state changes can occur.
- Returns
Implemented in Apache.Qpid.Proton.Engine.Implementation.ProtonEngine.
◆ IsWritable
|
get |
Returns true if the engine is accepting input from the ingestion entry points.
When false any attempts to write more data into the engine will result in an error being returned from the write operation. An engine that has not been started or that has been failed or shutdown will report as not writable.
Implemented in Apache.Qpid.Proton.Engine.Implementation.ProtonEngine.
◆ Pipeline
|
get |
Provides access to the engine pipeline instance associated with this engine.
Implemented in Apache.Qpid.Proton.Engine.Implementation.ProtonEngine.
◆ SaslDriver
|
get |
Provides access to the SASL driver that is assigned to this engine.
Implemented in Apache.Qpid.Proton.Engine.Implementation.ProtonEngine.
The documentation for this interface was generated from the following file:
- src/Proton/Engine/IEngine.cs
