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: TROBaseSuperConnection)

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: TROBaseSuperConnection read write

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

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

procedure Disconnected(var RestartLoop: Boolean)

Parameters:

  • RestartLoop: If set to true indicates that the connection is going 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

This method is called when the data package has been read from the socket.

procedure IncomingData(Id: Integer; aData: TStream)

Parameters:

  • Id: 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 write

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(iSender: TObject; iType: TProgressType; iDirection: TProgressDirection; iTransferred: integer; iTotal: 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(Data: TStream)

Parameters:

  • Data: 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

The method to send the higher level error messages to the remote party. Used to transmit package errors such as the package oversize.

procedure SendError(Id: Integer; Error: Byte)

Parameters:

  • Id: The package id to use when sending data.
  • Error: The error code.

SendOptions  protected

Sends the protocol options agreement package.

procedure SendOptions(aData: ROUTF8String)

Parameters:

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

SendPackage

Sends the package to the channel. The IntSendData method is used. For convenience this method is able to generate a new package id and acquire a write lock.

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

Parameters:

  • aData: The data to send, payload only.
  • Id: The package id to use, 0 may be passed to generate and use a new id.

SetAckDetails  protected virtual

procedure SetAckDetails(Id: Integer; Oke: Boolean; ErrorNo: Integer)

Parameters:

  • Id:
  • Oke:
  • ErrorNo:

SkipAck

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

The utility method to wait for acknowledgement package from the remote party and analyzes it's content. Throws exceptions if any errors detected.

class procedure WaitForAck(pkg: IROPackageAck; Timeout: Integer)

Parameters:

  • pkg: The object describing acknowledgement package.
  • Timeout: Package wait timeout.

 

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: TROBaseSuperConnection read write

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 write

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

property SkipAck: Boolean read write

 

WaitForAck

The utility method to wait for acknowledgement package from the remote party and analyzes it's content. Throws exceptions if any errors detected.

class procedure WaitForAck(pkg: IROPackageAck; Timeout: Integer)

Parameters:

  • pkg: The object describing acknowledgement package.
  • Timeout: Package wait timeout.

 

constructor Create

Creates the worker instance.

constructor Create(ABaseSuperConnection: TROBaseSuperConnection)

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

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

procedure Disconnected(var RestartLoop: Boolean)

Parameters:

  • RestartLoop: If set to true indicates that the connection is going 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

This method is called when the data package has been read from the socket.

procedure IncomingData(Id: Integer; aData: TStream)

Parameters:

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

ProcessOption  protected

Called to process protocol options agreement packages.

procedure ProcessOption(Data: TStream)

Parameters:

  • Data: 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

The method to send the higher level error messages to the remote party. Used to transmit package errors such as the package oversize.

procedure SendError(Id: Integer; Error: Byte)

Parameters:

  • Id: The package id to use when sending data.
  • Error: The error code.

SendOptions  protected

Sends the protocol options agreement package.

procedure SendOptions(aData: ROUTF8String)

Parameters:

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

SendPackage

Sends the package to the channel. The IntSendData method is used. For convenience this method is able to generate a new package id and acquire a write lock.

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

Parameters:

  • aData: The data to send, payload only.
  • Id: The package id to use, 0 may be passed to generate and use a new id.

SetAckDetails  protected virtual

procedure SetAckDetails(Id: Integer; Oke: Boolean; ErrorNo: Integer)

Parameters:

  • Id:
  • Oke:
  • ErrorNo:

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(iSender: TObject; iType: TProgressType; iDirection: TProgressDirection; iTransferred: integer; iTotal: integer)

Descendants