Class ACounter

DescriptionHierarchyFieldsMethodsProperties

Unit

Declaration

type ACounter = class(AStringLeaf)

Description

This class represents a single named counter. It is used primarily by instances of ALog to keep track of the quantities of various types of messages and errors that are logged. Each named counter can have a maximum value and can optionally throw an exception when that value is exceeded.

Counters descend from AStringLeaf so that they can be managed by name in a list of counters; this is done by ACounterList.

Hierarchy

Overview

Fields

Protected myValue: longword;
Protected myLimit: longword;
Protected myNotifyOnExcess: boolean;

Methods

Public constructor named(const thisName: string; const initialValue: longword = 0; const maximumValue: longword = 0); reintroduce; virtual;
Public function init: boolean; override;
Public procedure increment(const quantity: longword = 1); virtual;
Public procedure decrement(const quantity: longword = 1); virtual;
Public procedure zero; virtual;
Public function shallowCopyFrom(const Other: AnObject): boolean; override;
Public function selfStreamingLength: TStreamIOSize; override;
Public function writeSelfTo(const Dest: AStream): TStreamIOSize; override;
Public function readFrom(const Source: AStream): TStreamIOSize; override;
Public function toString: AnsiString; override;
Public function value: longword; virtual;
Public function limit: longword; virtual;
Public function setLimit(const newLimit: longword): longword; virtual;
Public function notifyOnExcess: boolean; virtual;
Public function setNotifyOnExcess(const flag: boolean): boolean; virtual;

Description

Fields

Protected myValue: longword;

Stores the value of the counter

Protected myLimit: longword;

Stores the maximum value of the counter

Protected myNotifyOnExcess: boolean;

Indicates whether or not the counter should throw an exception when its maximum value is exceeded.

Methods

Public constructor named(const thisName: string; const initialValue: longword = 0; const maximumValue: longword = 0); reintroduce; virtual;

Construct a new counter instance with a specific name, starting value and optional maximum value.

If maximumValue is zero (0), then the counter has no maximum.

Public function init: boolean; override;

Initializer

Public procedure increment(const quantity: longword = 1); virtual;

Increments the counter by the specified value.

After incrementing the value, this method checks to see whether the maximum value of the counter has been exceeded; if so, and if ACounter.notifyOnExcess is True, then it raises an exception.

Exceptions raised
ACounterOverageError
if all three of the following are true: the maximum value of the counter is specified (i.e., not zero [0]), that value is exceeded, and ACounter.notifyOnExcess is True.
Public procedure decrement(const quantity: longword = 1); virtual;

Decrements the counter by the specified value.

Counters cannot be decremented below zero (0).

Public procedure zero; virtual;

Resets the value of the counter to zero (0).

Public function shallowCopyFrom(const Other: AnObject): boolean; override;

Construct a shallow copy of the other object.

This method overrides the behavior inherited from AStringLeaf.shallowCopyFrom: it calls that routine, then checks to see whether Other is an instance of ACounter. If so, it copies the values of

from Other to Self, overwriting the values in Self.

Note that this method does NOT copy any sibling or child nodes and so cannot be used to create a full copy of any descendant of ANode. Likewise, it does NOT copy the left or right subtrees and so cannot be used to create a full copy of any descendant of ABinaryLeaf. The copy will NOT be automatically placed in the binary tree to which Other belongs, if any, but the caller is free to do so, so long as the node's sort key does not match one that already exists in the tree.

Public function selfStreamingLength: TStreamIOSize; override;

Calculate the number of bytes required to stream the counter, and just the counter.

This method builds upon the behavior inherited from AStringLeaf.selfStreamingLength: it calls the inherited routine, and then adds the number of bytes required to store the current value of the counter, its limit, and whether or not it should raise an exception on overages.

Public function writeSelfTo(const Dest: AStream): TStreamIOSize; override;

Write the counter, and just the counter, to the specified stream.

This method builds upon the behavior inherited from AStringLeaf.writeSelfTo: it calls the inherited routine first, then writes the current value of the counter, its limit, and whether or not it should raise an exception on overages.

Returns

The total number of bytes written to Dest.

Public function readFrom(const Source: AStream): TStreamIOSize; override;

Read the counter from the specified stream.

This method builds upon the behavior inherited from AStringLeaf.readFrom: it calls the inherited routine first, then reads the value of the counter, its limit, and whether or not it should raise an exception on overages from Source.

Returns

The total number of bytes read from Source.

Public function toString: AnsiString; override;

Construct and return a string representation of the counter and its value, suitable for printing to a text-based device, such as a console.

The string returned by this routine will include the name of the counter and its current value. The format of the string is controlled by cntrStringRepresentation.

Public function value: longword; virtual;

Return the current value of the counter.

Public function limit: longword; virtual;

Return the maximum value of the counter.

If ACounter.notifyOnExcess is True, then ACounter.increment will raise an exception if this value is exceeded.

Public function setLimit(const newLimit: longword): longword; virtual;

Set the maximum value of the counter.

If ACounter.notifyOnExcess is True, then ACounter.increment will raise an exception if the value specified by newLimit is exceeded.

Returns

The previous maximum value of the counter.

Public function notifyOnExcess: boolean; virtual;

Determine whether or not ACounter.increment will raise an exception when the value specified by ACounter.limit is exceeded.

By default, the initializer of ACounter sets this value to True.

Public function setNotifyOnExcess(const flag: boolean): boolean; virtual;

Set whether or not ACounter.increment will raise an exception when the value specified by ACounter.limit is exceeded.

Returns

The previous value of ACounter.limit.


Generated by PasDoc 0.13.0 on 2015-06-23 19:40:11