Back to index

nordugrid-arc-nox  1.1.0~rc6
Public Member Functions | Protected Types | Protected Member Functions | Private Member Functions | Friends
Arc::Counter Class Reference

A class defining a common interface for counters. More...

#include <Counter.h>

Inheritance diagram for Arc::Counter:
Inheritance graph
[legend]

List of all members.

Public Member Functions

virtual ~Counter ()
 The destructor.
virtual int getLimit ()=0
 Returns the current limit of the counter.
virtual int setLimit (int newLimit)=0
 Sets the limit of the counter.
virtual int changeLimit (int amount)=0
 Changes the limit of the counter.
virtual int getExcess ()=0
 Returns the excess limit of the counter.
virtual int setExcess (int newExcess)=0
 Sets the excess limit of the counter.
virtual int changeExcess (int amount)=0
 Changes the excess limit of the counter.
virtual int getValue ()=0
 Returns the current value of the counter.
virtual CounterTicket reserve (int amount=1, Glib::TimeVal duration=ETERNAL, bool prioritized=false, Glib::TimeVal timeOut=ETERNAL)=0
 Makes a reservation from the counter.

Protected Types

typedef unsigned long long int IDType
 A typedef of identification numbers for reservation.

Protected Member Functions

 Counter ()
 Default constructor.
virtual void cancel (IDType reservationID)=0
 Cancellation of a reservation.
virtual void extend (IDType &reservationID, Glib::TimeVal &expiryTime, Glib::TimeVal duration=ETERNAL)=0
 Extension of a reservation.
Glib::TimeVal getCurrentTime ()
 Get the current time.
Glib::TimeVal getExpiryTime (Glib::TimeVal duration)
 Computes an expiry time.
CounterTicket getCounterTicket (Counter::IDType reservationID, Glib::TimeVal expiryTime, Counter *counter)
 A "relay method" for a constructor of the CounterTicket class.
ExpirationReminder getExpirationReminder (Glib::TimeVal expTime, Counter::IDType resID)
 A "relay method" for the constructor of ExpirationReminder.

Private Member Functions

 Counter (const Counter &unique)
 Copy constructor, should not be used.
void operator= (const Counter &unique)
 Assignment operator, should not be used.

Friends

class CounterTicket
 The CounterTicket class needs to be a friend.
class ExpirationReminder
 The ExpirationReminder class needs to be a friend.

Detailed Description

A class defining a common interface for counters.

This class defines a common interface for counters as well as some common functionality.

The purpose of a counter is to provide housekeeping some resource such as e.g. disk space, memory or network bandwidth. The counter itself will not be aware of what kind of resource it limits the use of. Neither will it be aware of what unit is being used to measure that resource. Counters are thus very similar to semaphores. Furthermore, counters are designed to handle concurrent operations from multiple threads/processes in a consistent manner.

Every counter has a limit, an excess limit and a value. The limit is a number that specify how many units are available for reservation. The value is the number of units that are currently available for reservation, i.e. has not allready been reserved. The excess limit specify how many extra units can be reserved for high priority needs even if there are no normal units available for reservation. The excess limit is similar to the credit limit of e.g. a VISA card.

The users of the resource must thus first call the counter in order to make a reservation of an appropriate amount of the resource, then allocate and use the resource and finally call the counter again to cancel the reservation.

Typical usage is:

     // Declare a counter. Replace XYZ by some appropriate kind of
     // counter and provide required parameters. Unit is MB.
     XYZCounter memory(...);
     ...
     // Make a reservation of memory for 2000000 doubles.
     CounterTicket tick = memory.reserve(2*sizeof(double));
     // Use the memory.
     double* A=new double[2000000];
     doSomething(A);
     delete[] A;
     // Cancel the reservation.
     tick.cancel();

There are also alternative ways to make reservations, including self-expiring reservations, prioritized reservations and reservations that fail if they cannot be made fast enough.

For self expiring reservations, a duration is provided in the reserve call:

     tick = memory.reserve(2*sizeof(double), Glib::TimeVal(1,0));

A self-expiring reservation can be cancelled explicitly before it expires, but if it is not cancelled it will expire automatically when the duration has passed. The default value for the duration is ETERNAL, which means that the reservation will not be cancelled automatically.

Prioritized reservations may use the excess limit and succeed immediately even if there are no normal units available for reservation. The value of the counter will in this case become negative. A prioritized reservation looks like this:

     tick = memory.reserve(2*sizeof(double), Glib::TimeVal(1,0), true);

Finally, a time out option can be provided for a reservation. If some task should be performed within two seconds or not at all, the reservation can look like this:

     tick = memory.reserve(2*sizeof(double), Glib::TimeVal(1,0),
                          true, Glib::TimeVal(2,0));
     if (tick.isValid())
      doSomething(...);

Definition at line 103 of file Counter.h.


Member Typedef Documentation

typedef unsigned long long int Arc::Counter::IDType [protected]

A typedef of identification numbers for reservation.

This is a type that is used as identification numbesrs (keys) for referencing of reservations. It is used internally in counters for book keeping of reservations as well as in the CounterTicket class in order to be able to cancel and extend reservations.

Definition at line 114 of file Counter.h.


Constructor & Destructor Documentation

Arc::Counter::Counter ( ) [protected]

Default constructor.

This is the default constructor. Since Counter is an abstract class, it should only be used by subclasses. Therefore it is protected. Furthermore, since the Counter class has no attributes, nothing needs to be initialized and thus this constructor is empty.

Definition at line 18 of file Counter.cpp.

                   {
    // Nothing needs to be done.
  }
Arc::Counter::~Counter ( ) [virtual]

The destructor.

This is the destructor of the Counter class. Since the Counter class has no attributes, nothing needs to be cleaned up and thus the destructor is empty.

Definition at line 27 of file Counter.cpp.

                    {
    // Nothing needs to be done.
  }
Arc::Counter::Counter ( const Counter unique) [private]

Copy constructor, should not be used.

A private copy constructor, since Counters should never be copied. It should be impossible to use, but if that would happen by accident the program will exit with the EXIT_FAILURE code.

Definition at line 22 of file Counter.cpp.

                                 {
    // Executing this code should be impossible!
    exit(EXIT_FAILURE);
  }

Member Function Documentation

virtual void Arc::Counter::cancel ( IDType  reservationID) [protected, pure virtual]

Cancellation of a reservation.

This method cancels a reservation. It is called by the CounterTicket that corresponds to the reservation.

Parameters:
reservationIDThe identity number (key) of the reservation to cancel.

Implemented in Arc::IntraProcessCounter.

Here is the caller graph for this function:

virtual int Arc::Counter::changeExcess ( int  amount) [pure virtual]

Changes the excess limit of the counter.

Changes the excess limit of the counter by adding a certain amount to the current excess limit.

Parameters:
amountThe amount by which to change the excess limit.
Returns:
The new excess limit.

Implemented in Arc::IntraProcessCounter.

virtual int Arc::Counter::changeLimit ( int  amount) [pure virtual]

Changes the limit of the counter.

Changes the limit of the counter by adding a certain amount to the current limit.

Parameters:
amountThe amount by which to change the limit.
Returns:
The new limit.

Implemented in Arc::IntraProcessCounter.

virtual void Arc::Counter::extend ( IDType reservationID,
Glib::TimeVal &  expiryTime,
Glib::TimeVal  duration = ETERNAL 
) [protected, pure virtual]

Extension of a reservation.

This method extends a reservation. It is called by the CounterTicket that corresponds to the reservation.

Parameters:
reservationIDUsed for input as well as output. Contains the identification number of the original reservation on entry and the new identification number of the extended reservation on exit.
expiryTimeUsed for input as well as output. Contains the expiry time of the original reservation on entry and the new expiry time of the extended reservation on exit.
durationThe time by which to extend the reservation. The new expiration time is computed based on the current time, NOT the previous expiration time.

Implemented in Arc::IntraProcessCounter.

Here is the caller graph for this function:

CounterTicket Arc::Counter::getCounterTicket ( Counter::IDType  reservationID,
Glib::TimeVal  expiryTime,
Counter counter 
) [protected]

A "relay method" for a constructor of the CounterTicket class.

This method acts as a relay for one of the constructors of the CounterTicket class. That constructor is private, but needs to be accessible from the subclasses of Counter (bot not from anywhere else). In order not to have to declare every possible subclass of Counter as a friend of CounterTicket, only the base class Counter is a friend and its subclasses access the constructor through this method. (If C++ had supported "package access", as Java does, this trick would not have been necessary.)

Parameters:
reservationIDThe identity number of the reservation corresponding to the CounterTicket.
expiryTimethe expiry time of the reservation corresponding to the CounterTicket.
counterThe Counter from which the reservation has been made.
Returns:
The counter ticket that has been created.

Definition at line 49 of file Counter.cpp.

                                                            {
    return CounterTicket(reservationID, expiryTime, counter);
  }

Here is the caller graph for this function:

Glib::TimeVal Arc::Counter::getCurrentTime ( ) [protected]

Get the current time.

Returns the current time. An "adapter method" for the assign_current_time() method in the Glib::TimeVal class. return The current time.

Definition at line 36 of file Counter.cpp.

                                      {
    Glib::TimeVal currentTime;
    currentTime.assign_current_time();
    return currentTime;
  }

Here is the caller graph for this function:

virtual int Arc::Counter::getExcess ( ) [pure virtual]

Returns the excess limit of the counter.

Returns the excess limit of the counter, i.e. by how much the usual limit may be exceeded by prioritized reservations.

Returns:
The excess limit.

Implemented in Arc::IntraProcessCounter.

ExpirationReminder Arc::Counter::getExpirationReminder ( Glib::TimeVal  expTime,
Counter::IDType  resID 
) [protected]

A "relay method" for the constructor of ExpirationReminder.

This method acts as a relay for one of the constructors of the ExpirationReminder class. That constructor is private, but needs to be accessible from the subclasses of Counter (bot not from anywhere else). In order not to have to declare every possible subclass of Counter as a friend of ExpirationReminder, only the base class Counter is a friend and its subclasses access the constructor through this method. (If C++ had supported "package access", as Java does, this trick would not have been necessary.)

Parameters:
expTimethe expiry time of the reservation corresponding to the ExpirationReminder.
resIDThe identity number of the reservation corresponding to the ExpirationReminder.
Returns:
The ExpirationReminder that has been created.

Definition at line 55 of file Counter.cpp.

                                                                         {
    return ExpirationReminder(expTime, resID);
  }

Here is the caller graph for this function:

Glib::TimeVal Arc::Counter::getExpiryTime ( Glib::TimeVal  duration) [protected]

Computes an expiry time.

This method computes an expiry time by adding a duration to the current time.

Parameters:
durationThe duration.
Returns:
The expiry time.

Definition at line 42 of file Counter.cpp.

                                                         {
    if (duration < ETERNAL)
      return getCurrentTime() + duration;
    else
      return ETERNAL;
  }

Here is the call graph for this function:

Here is the caller graph for this function:

virtual int Arc::Counter::getLimit ( ) [pure virtual]

Returns the current limit of the counter.

This method returns the current limit of the counter, i.e. how many units can be reserved simultaneously by different threads without claiming high priority.

Returns:
The current limit of the counter.

Implemented in Arc::IntraProcessCounter.

virtual int Arc::Counter::getValue ( ) [pure virtual]

Returns the current value of the counter.

Returns the current value of the counter, i.e. the number of unreserved units. Initially, the value is equal to the limit of the counter. When a reservation is made, the the value is decreased. Normally, the value should never be negative, but this may happen if there are prioritized reservations. It can also happen if the limit is decreased after some reservations have been made, since reservations are never revoked.

Returns:
The current value of the counter.

Implemented in Arc::IntraProcessCounter.

void Arc::Counter::operator= ( const Counter unique) [private]

Assignment operator, should not be used.

A private assignment operator, since Counters should never be assigned. It should be impossible to use, but if that would happen by accident the program will exit with the EXIT_FAILURE code.

Definition at line 31 of file Counter.cpp.

                                        {
    // Executing this code should be impossible!
    exit(EXIT_FAILURE);
  }
virtual CounterTicket Arc::Counter::reserve ( int  amount = 1,
Glib::TimeVal  duration = ETERNAL,
bool  prioritized = false,
Glib::TimeVal  timeOut = ETERNAL 
) [pure virtual]

Makes a reservation from the counter.

This method makes a reservation from the counter. If the current value of the counter is too low to allow for the reservation, the method blocks until the reservation is possible or times out.

Parameters:
amountThe amount to reserve, default value is 1.
durationThe duration of a self expiring reservation, default is that it lasts forever.
prioritizedWhether this reservation is prioritized and thus allowed to use the excess limit.
timeOutThe maximum time to block if the value of the counter is too low, default is to allow "eternal" blocking.
Returns:
A CounterTicket that can be queried about the status of the reservation as well as for cancellations and extensions.

Implemented in Arc::IntraProcessCounter.

virtual int Arc::Counter::setExcess ( int  newExcess) [pure virtual]

Sets the excess limit of the counter.

This method sets a new excess limit for the counter.

Parameters:
newExcessThe new excess limit, an absolute number.
Returns:
The new excess limit.

Implemented in Arc::IntraProcessCounter.

virtual int Arc::Counter::setLimit ( int  newLimit) [pure virtual]

Sets the limit of the counter.

This method sets a new limit for the counter.

Parameters:
newLimitThe new limit, an absolute number.
Returns:
The new limit.

Implemented in Arc::IntraProcessCounter.


Friends And Related Function Documentation

friend class CounterTicket [friend]

The CounterTicket class needs to be a friend.

Definition at line 312 of file Counter.h.

friend class ExpirationReminder [friend]

The ExpirationReminder class needs to be a friend.

Definition at line 315 of file Counter.h.


The documentation for this class was generated from the following files: