TROBaseSuperChannelWorker

Overview

This is the base class for all background worker classes used by super channels, both client ans server side. Background workers are executed on background threads and support the major part of the channel functionality and asynchronous behavior of superchannels. This class is abstract, there are two derived classes used instead: TROSCClientWorker and TROSCServerWorker for client and server side respectively.
This class is internal use only, is not intended to be used by users.

Location


 

constructor Create

Creates the worker instance.

constructor Create(ABaseSuperConnection: TROBaseSuperTcpConnection)

Parameters:

  • ABaseSuperConnection: The connection object to be associated with the worker, TROBaseSuperConnection instance.

BaseSuperConnection  protected

Provides read-only access to the connection object (incoming or outgoing) that is paired with the worker object. The connection object is a TROBaseSuperConnection descendant and is assigned by the constructor.

property BaseSuperConnection: TROBaseSuperTcpConnection read

BeginWriteLock

Acquires a lock using the internal synchronization object, used to synchronize write access to the underlying socket.

procedure BeginWriteLock

ClientID

Gets or set the client unique identifer.

property ClientID: TGuid read write

Connected  protected virtual

Called after the connection to the remote party established to do any specific actions at this moment.

procedure Connected

Disconnect

Instructs the connection object to disconnect.

procedure Disconnect

Disconnected  protected virtual

Sets the worker to disconnected state.

procedure Disconnected(var aRestartLoop: Boolean)

Parameters:

  • aRestartLoop: True value of this parameter indicates that the connection has to be reestablished.

DoExecute

The main processing method that is executed on a background thread.

procedure DoExecute

EndWriteLock

Releases a lock using the internal synchronization object, used to synchronize write access to the underlying socket.

procedure EndWriteLock

GenerateId

Used to generate a new package identifier in a thread safe manner. The package id is actually an order number of the data package (remote requests transmitted from clients to servers and events data transmitted from servers to clients) transmitted since the superchannel start. It increments from 1 to MaxInt for clients and decrements from -1 down to -MaxInt for servers. This method acquires a write lock prior to generate a new package id.

function GenerateId: Integer

GetDefaultResponse  protected virtual

Returns a string that is transmitted to the socket in case of any superchannel protocol error. Superchannel protocol errors can happen when the remote party behavior differs from the one expected according to the superchannel protocol. Usually this happens when non-super channel is used on the remote side or remote superchannel implementation has errors.

function GetDefaultResponse: string

Idle  protected virtual

This method is executed when the channel enters idle state: existing connection is disconnected and a new one is not established yet.

procedure Idle

IncomingData  protected virtual abstract

Called to process protocol options agreement packages.

procedure IncomingData(aId: Integer; aData: TStream)

Parameters:

  • aId: The package id received.
  • aData: The stream containing the incoming data, payload only.

IntSendData  protected

Called to process protocol options agreement packages.

function IntSendData(aId: Integer; aData: TStream): IROPackageAck

Parameters:

  • aId: The package id received.
  • aData: The stream containing the incoming data, payload only.

IsConnected

Allows to get or set the connected state flag that indicates wether the connection associated with the worker is established.

property IsConnected: Boolean read write

IsServer  protected

Allows to get or set the flag that allows to distinguish client side worker from server ones. The value for this flag is set once by the constructor code of the derived class and is used by the unified code that supports superchannel protocol.

property IsServer: Boolean read write

LastData  protected

Allows to get the last channel activity date and time. This value is reset every time the channel is about to send a data package or received one.

property LastData: TDateTime read

MaxPackageSize

Determines the maximum size of the package that can be transmitted through the channel. The worker code compares this value to the data size to be transmitted and throws an exception in case of oversize.

property MaxPackageSize: Integer read write

OnProgress

This event is fired while buffered data transmission is performed (IntSendData and ReadStream methods). The event is fired after each data portion transmitted.

property OnProgress: TProgressEvent read write
delegate:  procedure OnProgress(aSender: TObject; aType: TProgressType; aDirection: TProgressDirection; aTransferred: Integer; aTotal: Integer)

PingFrequency  protected

Determines the time interval in seconds between attempts to send a ping package (such packages are used to make sure the remote party is up ad running, has nothing to with ICMP pings).

property PingFrequency: Integer read write

PingTimeout  protected

Determines the time interval in seconds for remote party to answer a ping request package (such packages are used to make sure the remote party is up and running, has nothing to with ICMP pings). If ping request was not answered than the connection is considered broken so the client side reconnects and the server side removes the lost connection data from the memory.

property PingTimeout: Integer read write

ProcessOption  protected

Called to process protocol options agreement packages.

procedure ProcessOption(aData: TStream)

Parameters:

  • aData: The stream containing the options agreement package.

ReadStream  protected

Performs the buffered read from the associated connection object (finally from the socket).

function ReadStream(aDest: TStream; aLen: Integer): Boolean

Parameters:

  • aDest: The stream to place the data into.
  • aLen: The number of bytes to read.

SendError

Called to process protocol options agreement packages.

procedure SendError(aId: Integer; aError: Byte)

Parameters:

  • aId: The package id received.
  • aError: The stream containing the incoming data, payload only.

SendOptions  protected

Sends the protocol options agreement package.

procedure SendOptions(aData: ROUTF8String)

Parameters:

  • aData: The package content, in the string form.

SendPackage

Called to process protocol options agreement packages.

function SendPackage(aData: TStream; aId: Integer): IROPackageAck

Parameters:

  • aData: The package id received.
  • aId: The stream containing the incoming data, payload only.

SetAckDetails  protected virtual

procedure SetAckDetails(aId: Integer; aOk: Boolean; aErrorNo: Integer)

Parameters:

  • aId:
  • aOk:
  • aErrorNo:

SkipAck

Defines whether "acknowledgement" messages are skipped.

property SkipAck: Boolean read write

SupportsOptions  protected

Called when the remote party initiates the protocol options agreement. Calls SendOptions to send the required options information.

procedure SupportsOptions

WaitForAck

Called to process protocol options agreement packages.

class procedure WaitForAck(aPackage: IROPackageAck; aTimeout: Integer)

Parameters:

  • aPackage: The package id received.
  • aTimeout: The stream containing the incoming data, payload only.

 

BaseSuperConnection  protected

Provides read-only access to the connection object (incoming or outgoing) that is paired with the worker object. The connection object is a TROBaseSuperConnection descendant and is assigned by the constructor.

property BaseSuperConnection: TROBaseSuperTcpConnection read

ClientID

Gets or set the client unique identifer.

property ClientID: TGuid read write

IsConnected

Allows to get or set the connected state flag that indicates wether the connection associated with the worker is established.

property IsConnected: Boolean read write

IsServer  protected

Allows to get or set the flag that allows to distinguish client side worker from server ones. The value for this flag is set once by the constructor code of the derived class and is used by the unified code that supports superchannel protocol.

property IsServer: Boolean read write

LastData  protected

Allows to get the last channel activity date and time. This value is reset every time the channel is about to send a data package or received one.

property LastData: TDateTime read

MaxPackageSize

Determines the maximum size of the package that can be transmitted through the channel. The worker code compares this value to the data size to be transmitted and throws an exception in case of oversize.

property MaxPackageSize: Integer read write

PingFrequency  protected

Determines the time interval in seconds between attempts to send a ping package (such packages are used to make sure the remote party is up ad running, has nothing to with ICMP pings).

property PingFrequency: Integer read write

PingTimeout  protected

Determines the time interval in seconds for remote party to answer a ping request package (such packages are used to make sure the remote party is up and running, has nothing to with ICMP pings). If ping request was not answered than the connection is considered broken so the client side reconnects and the server side removes the lost connection data from the memory.

property PingTimeout: Integer read write

SkipAck

Defines whether "acknowledgement" messages are skipped.

property SkipAck: Boolean read write

 

WaitForAck

Called to process protocol options agreement packages.

class procedure WaitForAck(aPackage: IROPackageAck; aTimeout: Integer)

Parameters:

  • aPackage: The package id received.
  • aTimeout: The stream containing the incoming data, payload only.

 

constructor Create

Creates the worker instance.

constructor Create(ABaseSuperConnection: TROBaseSuperTcpConnection)

Parameters:

  • ABaseSuperConnection: The connection object to be associated with the worker, TROBaseSuperConnection instance.

BeginWriteLock

Acquires a lock using the internal synchronization object, used to synchronize write access to the underlying socket.

procedure BeginWriteLock

Connected  protected virtual

Called after the connection to the remote party established to do any specific actions at this moment.

procedure Connected

Disconnect

Instructs the connection object to disconnect.

procedure Disconnect

Disconnected  protected virtual

Sets the worker to disconnected state.

procedure Disconnected(var aRestartLoop: Boolean)

Parameters:

  • aRestartLoop: True value of this parameter indicates that the connection has to be reestablished.

DoExecute

The main processing method that is executed on a background thread.

procedure DoExecute

EndWriteLock

Releases a lock using the internal synchronization object, used to synchronize write access to the underlying socket.

procedure EndWriteLock

GenerateId

Used to generate a new package identifier in a thread safe manner. The package id is actually an order number of the data package (remote requests transmitted from clients to servers and events data transmitted from servers to clients) transmitted since the superchannel start. It increments from 1 to MaxInt for clients and decrements from -1 down to -MaxInt for servers. This method acquires a write lock prior to generate a new package id.

function GenerateId: Integer

GetDefaultResponse  protected virtual

Returns a string that is transmitted to the socket in case of any superchannel protocol error. Superchannel protocol errors can happen when the remote party behavior differs from the one expected according to the superchannel protocol. Usually this happens when non-super channel is used on the remote side or remote superchannel implementation has errors.

function GetDefaultResponse: string

Idle  protected virtual

This method is executed when the channel enters idle state: existing connection is disconnected and a new one is not established yet.

procedure Idle

IncomingData  protected virtual abstract

Called to process protocol options agreement packages.

procedure IncomingData(aId: Integer; aData: TStream)

Parameters:

  • aId: The package id received.
  • aData: The stream containing the incoming data, payload only.

IntSendData  protected

Called to process protocol options agreement packages.

function IntSendData(aId: Integer; aData: TStream): IROPackageAck

Parameters:

  • aId: The package id received.
  • aData: The stream containing the incoming data, payload only.

ProcessOption  protected

Called to process protocol options agreement packages.

procedure ProcessOption(aData: TStream)

Parameters:

  • aData: The stream containing the options agreement package.

ReadStream  protected

Performs the buffered read from the associated connection object (finally from the socket).

function ReadStream(aDest: TStream; aLen: Integer): Boolean

Parameters:

  • aDest: The stream to place the data into.
  • aLen: The number of bytes to read.

SendError

Called to process protocol options agreement packages.

procedure SendError(aId: Integer; aError: Byte)

Parameters:

  • aId: The package id received.
  • aError: The stream containing the incoming data, payload only.

SendOptions  protected

Sends the protocol options agreement package.

procedure SendOptions(aData: ROUTF8String)

Parameters:

  • aData: The package content, in the string form.

SendPackage

Called to process protocol options agreement packages.

function SendPackage(aData: TStream; aId: Integer): IROPackageAck

Parameters:

  • aData: The package id received.
  • aId: The stream containing the incoming data, payload only.

SetAckDetails  protected virtual

procedure SetAckDetails(aId: Integer; aOk: Boolean; aErrorNo: Integer)

Parameters:

  • aId:
  • aOk:
  • aErrorNo:

SupportsOptions  protected

Called when the remote party initiates the protocol options agreement. Calls SendOptions to send the required options information.

procedure SupportsOptions

 

OnProgress

This event is fired while buffered data transmission is performed (IntSendData and ReadStream methods). The event is fired after each data portion transmitted.

property OnProgress: TProgressEvent read write
delegate:  procedure OnProgress(aSender: TObject; aType: TProgressType; aDirection: TProgressDirection; aTransferred: Integer; aTotal: Integer)