Indy 9 | Content | Index | Reference

TIdIOHandlerThrottle
Hierarchy, Properties, Methods, Events, See Also, Unit: IdIOHandlerThrottle
Implements an IOHandler used to restrict throughput to a targeted number of bytes per second.

    TIdIOHandlerThrottle = class(TIdIOHandler)

Unit
IdIOHandlerThrottle
Description
TIdIOHandlerThrottle is a TIdIOHandler descendant used to restrict the throughput for an associated IOHandler to a targeted number of bytes per second for Send and Receive operations. TIdIOHandlerThrottle attaches to an existing IOHandler to perform its specific function.

TIdIOHandlerThrottle overrides methods in the ancestor class, like :

- Close

- ConnectClient

- Connected

- Open

- Readable

- Recv

- Send

TIdIOHandlerThrottle also publishes properties like:

- BytesPerSec

- BitsPerSec

- ChainedHandler

TIdIOHandlerThrottle.BitsPerSec
TIdIOHandlerThrottle, See Also
Get or Set the throughput of the IOHandler using a targeted number of Bits per Second.

    property BitsPerSec: Cardinal;

Description
BitsPerSec is a Cardinal property that indicates the throughtput for the Send and Recv for the associated IOHandler in ChainedHandler expressed in Bits per Second (as opposed to Bytes per Second). BitsPerSec is a calculated product using the formula BytesPerSec multiplied by 8. Changing the value in BitsPerSec will result in BytesPerSec being updated to contain the integer result of the new value divided by 8.

Use BytesPerSec to examine or change the target throughput of the IOHandler using an 8-bit Bytes per Second value.

TIdIOHandlerThrottle.BytesPerSec
TIdIOHandlerThrottle, See Also
Indicates the targeted throughput for Send and Recv operations for the IOHandler.

    property BytesPerSec: Cardinal;

Description
BytesPerSec is a Cardinal property that represents the targeted throughput for Send and Recv using the associated IOHandler in ChainedHandler. BytesPerSec is used in Recv and Send to determine when the throughput for the associated IOHandler in ChainedHandler needs to be restricted in order to meet the target value in the property.

When BytesPerSec contains the value 0 (zero), no bandwidth restriction is performed for the associated IOHandler in ChainedHandler. In this situation, ChainedHandler calls its Recv or Send method immediately.

Use BitsPerSec to get or set the targeted throughput using bits per second instead of bytes per second.

TIdIOHandlerThrottle.ChainedHandler
TIdIOHandlerThrottle, See Also
Represents the actual IOHandler used for send and receive operations for a socket connection.

    property ChainedHandler: TIdIOHandler;

Description
ChainedHandler is a TIdIOHandler property that represents the actual IOHandler performing Recv and Send operations. ChainedHandler is used in ConnectClient to establish the connection using the desired Host, Port, and BoundPort number for the client. ChainedHandler is used in methods like Open, Close, Connected, and Readable.

ChainedHandler must be assigned a valid TIdIOHandler instance, or an EIdThrottleNoChainedIOHandler exception wil be raised during execution in ConnectClient and Open.

TIdIOHandlerThrottle.Close
TIdIOHandlerThrottle, See Also
Closes the chained IOHandler.

    procedure Close; override;

Description
Close is an overridden procedure in TIdIOHandlerThrottle, and allows the associated IOHandler descendant in ChainedHandler to be closed. When a valid IOHandler instance has been assigned to ChainedHandler, its Close method is called prior to exiting from the method.

TIdIOHandlerThrottle.ConnectClient
TIdIOHandlerThrottle, See Also
Prepares and opens the client connection for a chained IOHandler.

    procedure ConnectClient(const AHost: string; const APort: Integer; const ABoundIP: string; const ABoundPort: Integer; const ABoundPortMin: Integer; const ABoundPortMax: Integer; const ATimeout: Integer = IdTimeoutDefault); override;

Parameters
const AHost: string
Address of the remote system for the client connection.
const APort: Integer
Port number for the remote connection.
const ABoundIP: string
IP Address bound to the local system.
const ABoundPort: Integer
Integer - Port number bound to the local computer.
const ABoundPortMin: Integer
Minimum bound port number for the local system.
const ABoundPortMax: Integer
Maximum bound port number for the local system.
const ATimeout: Integer = IdTimeoutDefault
Number of milliseconds to wait before a connection attempt fails. Default value is IdTimeoutDefault.
Description
ConnectClient is an overriden procedure in TIdIOHandlerThrottle that prepares and established the client connection for the associated IOHandler in ChainedHandler. ConnectClient calls the inherited ConnectClient method.

When a valid instance of an IOHandler descendant has been assigned to ChainedHandler, its ConnectClient mehod is called using the parameters for the method. Note: ConnectClient will raised an EIdThrottleNoChainedIOHandler exception with the message RSIHTChainedNotAssigned if a valid IOHandler instance is not assigned to ChainedHandler.

TIdIOHandlerThrottle.Connected
TIdIOHandlerThrottle, See Also
Indicates if physical connection for the chained IOHandler is prepared and opened.

    function Connected: Boolean; override;

Description
Connected is an overridden Boolean function in TIdIOHandlerThrottle, and determines when the physical connection for the associated IOHandler in ChainedHandler has been established. When a valid instance of a TIdIOHandler descendant has been assigned to ChainedHandler, its Connected method is called. When ChainedHandler is unassigned, Connected returns the value False.

Use Open to prepare the physical connection for the chained IOHandler, and ConnectClient to establish the connection used by the chained IOHandler.

TIdIOHandlerThrottle.Create
TIdIOHandlerThrottle, See Also
Constructor for the object instance.

    constructor Create(AOwner: TComponent); override;

Parameters
AOwner: TComponent
Owner of the object instance.
Description
Create is the constructor for the object instance. Create calls the inherited Create method using AOwner as the owner of the object instance.

TIdIOHandlerThrottle.Destroy
TIdIOHandlerThrottle, See Also
Frees an object instance.

    destructor Destroy; override;

Description
Destroy is the destructor for the object instance. Destroy calls the inherited Destroy method prior to exiting from the method.

TIdIOHandlerThrottle.Open
TIdIOHandlerThrottle, See Also
Prepares and binds the connection for a chained IOHandler.

    procedure Open; override;

Description
Open is an overriden method in TIdIOHandlerThrottle that prepares and binds the connection for the chained IOHandler. Open calls the inherited Open method.

When a valid instance of a TIdIOHandler descendant has been assigned to ChainedHandler, its Open method is called. Note: When ChainedHandler is unassigned, Open will raised an EIdThrottleNoChainedIOHandler exception with the message RSIHTChainedNotAssigned.

Use ConnectClient to establish the connection on the socket handle used by the handler. Use Close to disconnect the client connection in the chained IOHandler.

TIdIOHandlerThrottle.Readable
TIdIOHandlerThrottle, See Also
Indicates that the chained IOHandler is ready to send or receive data.

    function Readable(AMSec: integer = IdTimeoutDefault): boolean; override;

Parameters
AMSec: integer = IdTimeoutDefault
Milliseconds to wait for the IOHandler to become ready. Default value is IdTimeoutDefault.
Return Value
Boolean - True when ready.
Description
Readable is an overidden Boolean function in TIdIOHandlerThrottle that indicates if associated IOHandler in ChainedHandler is ready for input/output operations.

When ChainedHandler contains a valid instance of a TIdIOHandler descendant, its Readable method is called using the value in AMSec as a parameter. The return value for the method is set to the result of the operation. When ChainedHandler is unassigned, the return value for the method is set to False.

TIdIOHandlerThrottle.Recv
TIdIOHandlerThrottle, See Also
Reads data from a chained IOHandler.

    function Recv(var ABuf; ALen: integer): integer; override;

Parameters
var ABuf
Destination buffer for values read from the chained IOHandler.
ALen: integer
Number of bytes to read from the connection.
Return Value
Integer - Acutal number of bytes read from the chained IOHandler.
Description
Recv is an overridden Integer function that read data using the IOHandler in ChainedHandler. When a valid instance of a TIdIOHandler descendant is assigned to ChainedHandler, Recv will attempt to limit the throughtput for the chained IOHandler when BytesPerSec contains a value greater than 0 (zero).

When BytesPerSec is 0 (or less), no throughput leveling is performed, and the Recv method for the ChainedHandler is called using ABuf and ALen as parameters.

Recv limits throughput by forcing the IOHandler to delay when the elapsed time for a read operation is smaller than the estimated time required to read ALen bytes at the desired BytesPerSec rate. The delay will level the throughput rate, on average, to the desired target.

Use Send to write data using the chained IOHandler.

TIdIOHandlerThrottle.Send
TIdIOHandlerThrottle, See Also
Writes data using a chained IOHandler.

    function Send(var ABuf; ALen: integer): integer; override;

Parameters
var ABuf
Buffer for values written using the chained IOHandler.
ALen: integer
Number of bytes to write using the chained IOHandler.
Return Value
Integer - Acutal number of bytes written using the chained IOHandler.
Description
Send is an overridden Integer function that writes data using the IOHandler in ChainedHandler. When a valid instance of a TIdIOHandler descendant is assigned to ChainedHandler, Send will attempt to limit the throughtput for the chained IOHandler when BytesPerSec contains a value greater than 0 (zero).

When BytesPerSec is 0 (or less), no throughput leveling is performed, and the Send method for the ChainedHandler is called using ABuf and ALen as parameters.

Send limits throughput by forcing the IOHandler to delay when the elapsed time for a write operation is smaller than the estimated time required to write ALen bytes at the desired BytesPerSec rate. The delay will level the throughput rate, on average, to the desired target.

Use Recv to read data using the chained IOHandler.

Created with Doc-O-Matic 2 donated to Project JEDI. Commercial license available from the Doc-O-Matic site.