Back to index

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

A class for counters used by threads within a single process. More...

#include <IntraProcessCounter.h>

Inheritance diagram for Arc::IntraProcessCounter:
Inheritance graph
[legend]
Collaboration diagram for Arc::IntraProcessCounter:
Collaboration graph
[legend]

List of all members.

Public Member Functions

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

Protected Types

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

Protected Member Functions

virtual void cancel (IDType reservationID)
 Cancellation of a reservation.
virtual void extend (IDType &reservationID, Glib::TimeVal &expiryTime, Glib::TimeVal duration=ETERNAL)
 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

 IntraProcessCounter (const IntraProcessCounter &unique)
 Copy constructor, should not be used.
void operator= (const IntraProcessCounter &unique)
 Assignment operator, should not be used.
int unsafeGetValue ()
 Computes and returns the value of the counter.
int unsafeCancel (IDType reservationID)
 Cancels a reservation.
IDType unsafeReserve (int amount, Glib::TimeVal duration)
 Makes a reservation.
Glib::TimeVal unsafeGetNextExpiration ()
 Returns the expiry time for the next expiring reservation.

Private Attributes

int limit
 The limit of the counter.
int excess
 The excess limit of the counter.
int value
 The value of the counter.
IDType nextReservationID
 The identification number of the next reservation.
std::map< IDType, int > reservations
 Maps identification numbers of reservations to amounts.
std::priority_queue
< ExpirationReminder
selfExpiringReservations
 Contains expiration reminders of self-expiring reservations.
Glib::Mutex synchMutex
 A mutex that protects the attributes.
Glib::Cond synchCond
 A condition used for waiting for waiting for a higher value.

Detailed Description

A class for counters used by threads within a single process.

This is a class for shared among different threads within a single process. See the Counter class for further information about counters and examples of usage.

Definition at line 22 of file IntraProcessCounter.h.


Member Typedef Documentation

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

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::IntraProcessCounter::IntraProcessCounter ( int  limit,
int  excess 
)

Creates an IntraProcessCounter with specified limit and excess.

This constructor creates a counter with the specified limit (amount of resources available for reservation) and excess limit (an extra amount of resources that may be used for prioritized reservations).

Parameters:
limitThe limit of the counter.
excessThe excess limit of the counter.

Definition at line 15 of file IntraProcessCounter.cpp.

    : limit(limit),
      excess(excess),
      value(limit),
      nextReservationID(1) {
    // Nothing else needs to be done.
  }

Destructor.

This is the destructor of the IntraProcessCounter class. Does not need to do anything.

Definition at line 29 of file IntraProcessCounter.cpp.

                                            {
    // Nothing needs to be done.
  }

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 23 of file IntraProcessCounter.cpp.

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

Member Function Documentation

void Arc::IntraProcessCounter::cancel ( IDType  reservationID) [protected, 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.

Implements Arc::Counter.

Definition at line 116 of file IntraProcessCounter.cpp.

                                                                       {
    synchMutex.lock();
    unsafeCancel(reservationID);
    synchMutex.unlock();
    synchCond.signal();
  }

Here is the call graph for this function:

int Arc::IntraProcessCounter::changeExcess ( int  amount) [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.

Implements Arc::Counter.

Definition at line 74 of file IntraProcessCounter.cpp.

                                                  {
    int newExcess;
    synchMutex.lock();
    newExcess = excess + amount;
    excess += amount;
    synchMutex.unlock();
    synchCond.signal();
    return newExcess;
  }
int Arc::IntraProcessCounter::changeLimit ( int  amount) [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.

Implements Arc::Counter.

Definition at line 51 of file IntraProcessCounter.cpp.

                                                 {
    int newLimit;
    synchMutex.lock();
    newLimit = limit + amount;
    value += amount;
    limit = newLimit;
    synchMutex.unlock();
    synchCond.signal();
    return newLimit;
  }
void Arc::IntraProcessCounter::extend ( IDType reservationID,
Glib::TimeVal &  expiryTime,
Glib::TimeVal  duration = ETERNAL 
) [protected, 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.

Implements Arc::Counter.

Definition at line 123 of file IntraProcessCounter.cpp.

                                                         {
    int amount;
    synchMutex.lock();
    amount = unsafeCancel(reservationID);
    if (amount > 0) {
      expiryTime = getExpiryTime(duration);
      reservationID = unsafeReserve(amount, expiryTime);
    }
    else {
      expiryTime = HISTORIC;
      reservationID = 0;
    }
    synchMutex.unlock();
    synchCond.signal();
  }

Here is the call graph for this function:

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

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, inherited]

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:

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.

Implements Arc::Counter.

Definition at line 62 of file IntraProcessCounter.cpp.

                                     {
    return excess;
  }
ExpirationReminder Arc::Counter::getExpirationReminder ( Glib::TimeVal  expTime,
Counter::IDType  resID 
) [protected, inherited]

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, inherited]

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:

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.

Implements Arc::Counter.

Definition at line 38 of file IntraProcessCounter.cpp.

                                    {
    return limit;
  }

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.

Implements Arc::Counter.

Definition at line 84 of file IntraProcessCounter.cpp.

                                    {
    int result;
    synchMutex.lock();
    result = unsafeGetValue();
    synchMutex.unlock();
    return result;
  }

Here is the call graph for this function:

void Arc::IntraProcessCounter::operator= ( const IntraProcessCounter 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 33 of file IntraProcessCounter.cpp.

                                                                {
    // Executing this code should be impossible!
    exit(EXIT_FAILURE);
  }
CounterTicket Arc::IntraProcessCounter::reserve ( int  amount = 1,
Glib::TimeVal  duration = ETERNAL,
bool  prioritized = false,
Glib::TimeVal  timeOut = ETERNAL 
) [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.

Implements Arc::Counter.

Definition at line 92 of file IntraProcessCounter.cpp.

                                                                  {
    Glib::TimeVal deadline = getExpiryTime(timeOut);
    Glib::TimeVal expiryTime;
    IDType reservationID;
    synchMutex.lock();
    while (amount > unsafeGetValue() + (prioritized ? excess : 0) and
           getCurrentTime() < deadline)
      synchCond.timed_wait(synchMutex,
                           std::min(deadline, unsafeGetNextExpiration()));
    if (amount <= unsafeGetValue() + (prioritized ? excess : 0)) {
      expiryTime = getExpiryTime(duration);
      reservationID = unsafeReserve(amount, expiryTime);
    }
    else {
      expiryTime = HISTORIC;
      reservationID = 0;
    }
    synchMutex.unlock();
    return getCounterTicket(reservationID, expiryTime, this);
  }

Here is the call graph for this function:

int Arc::IntraProcessCounter::setExcess ( int  newExcess) [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.

Implements Arc::Counter.

Definition at line 66 of file IntraProcessCounter.cpp.

                                                  {
    synchMutex.lock();
    excess = newExcess;
    synchMutex.unlock();
    synchCond.signal();
    return newExcess;
  }
int Arc::IntraProcessCounter::setLimit ( int  newLimit) [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.

Implements Arc::Counter.

Definition at line 42 of file IntraProcessCounter.cpp.

                                                {
    synchMutex.lock();
    value += newLimit - limit;
    limit = newLimit;
    synchMutex.unlock();
    synchCond.signal();
    return newLimit;
  }
int Arc::IntraProcessCounter::unsafeCancel ( IDType  reservationID) [private]

Cancels a reservation.

Cancels a reservation with the specified identification number, i.e. removes that entry from the reservations map and increases the value by the corresponding amount. This method is not thread-safe by itself and should only be called from other methods that have allready locked synchMutex.

Parameters:
reservationIDThe identification number of the reservation to cancel.
Returns:
The amount that was reseved, or zero if there was no reservation with the specified identification number.

Definition at line 149 of file IntraProcessCounter.cpp.

                                                            {
    std::map<IDType, int>::iterator resIter = reservations.find(reservationID);
    int amount = 0;
    if (resIter != reservations.end()) {
      amount = resIter->second;
      value += amount;
      reservations.erase(resIter);
    }
    return amount;
  }

Here is the caller graph for this function:

Returns the expiry time for the next expiring reservation.

Returns the expiry time for the next expiring reservation, i.e. the expiry time of the top entry of the selfExpiringReservations priority queue.

Returns:
The expiry time for the next expiring reservation.

Definition at line 171 of file IntraProcessCounter.cpp.

                                                           {
    if (selfExpiringReservations.empty())
      return ETERNAL;
    else
      return selfExpiringReservations.top().getExpiryTime();
  }

Here is the caller graph for this function:

Computes and returns the value of the counter.

Cancels any pending reservations that have expired and returns the value of the counter. This method is not thread-safe by itself and should only be called from other methods that have allready locked synchMutex.

Returns:
The value of the counter.

Definition at line 141 of file IntraProcessCounter.cpp.

                                          {
    while (unsafeGetNextExpiration() < getCurrentTime()) {
      unsafeCancel(selfExpiringReservations.top().getReservationID());
      selfExpiringReservations.pop();
    }
    return value;
  }

Here is the call graph for this function:

Here is the caller graph for this function:

Counter::IDType Arc::IntraProcessCounter::unsafeReserve ( int  amount,
Glib::TimeVal  duration 
) [private]

Makes a reservation.

Makes a reservation of the specified amount for the specified duration and returns the identification number of the reservation. This method is not thread-safe by itself and should only be called from other methods that have allready locked synchMutex. Furthermore, it assumes that the calling method has allready asserted that the specified amount is available for reservation.

Parameters:
amountThe amount to reserve. The duration of the reservation.
Returns:
The identification number of the reservation.

Definition at line 160 of file IntraProcessCounter.cpp.

                                                                             {
    IDType reservationID = nextReservationID++;
    value -= amount;
    reservations[reservationID] = amount;
    if (expiryTime < ETERNAL)
      selfExpiringReservations.push(getExpirationReminder(expiryTime,
                                                          reservationID));
    return reservationID;
  }

Here is the call graph for this function:

Here is the caller graph for this function:


Member Data Documentation

The excess limit of the counter.

The current excess limit of the counter. Should not be altered unless synchMutex is locked.

Definition at line 221 of file IntraProcessCounter.h.

The limit of the counter.

The current limit of the counter. Should not be altered unless synchMutex is locked.

Definition at line 215 of file IntraProcessCounter.h.

The identification number of the next reservation.

The attribute holds the identification number of the next reservation. When a new identification number is needed, this number is used and the attribute is incremented in order to hold a number that is available for the next reservation. Should not be altered unless synchMutex is locked.

Definition at line 236 of file IntraProcessCounter.h.

Maps identification numbers of reservations to amounts.

This is a map that uses identification numbers of reservations as keys and maps them to the corresponding amounts amounts.

Definition at line 242 of file IntraProcessCounter.h.

Contains expiration reminders of self-expiring reservations.

This priority queue contains expiration reminders of self-expiring reservations. The next reservation to expire is allways at the top.

Definition at line 249 of file IntraProcessCounter.h.

A condition used for waiting for waiting for a higher value.

This condition is used when a reservation cannot be made immediately because the ammount that shall be reserved is larger than what is currently available.

Definition at line 263 of file IntraProcessCounter.h.

Glib::Mutex Arc::IntraProcessCounter::synchMutex [private]

A mutex that protects the attributes.

This mutex is used for protection of attributes from concurrent access from several threads. Any method that alter an attribute should lock this mutex.

Definition at line 256 of file IntraProcessCounter.h.

The value of the counter.

The current value of the counter. Should not be altered unless synchMutex is locked.

Definition at line 227 of file IntraProcessCounter.h.


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