3.2 The ACE_Time_Value Class

Ru-Brd

Motivation

Different operating systems provide different functions and data to access and manipulate the time and date. For example, UNIX platforms define the timeval structure as follows :

 struct timeval {    long secs;    long usecs;  }; 

Different date and time representations are used on other OS platforms, such as POSIX, Windows, and proprietary real-time operating systems. Time values are used in a number of situations, including timeout specifiers. As described in Sidebar 6 (page 45), ACE specifies timeouts in absolute time for some situations, such as the concurrency and synchronization wrapper facades in C++NPv1, and in relative time for other situations, such as the ACE_Reactor I/O timeouts and timer settings. The wide range of uses and different representations across platforms makes addressing these portability differences in each application unnecessarily tedious and costly, which is why the ACE Reactor framework provides the ACE_Time_Value class.

Class Capabilities

ACE_Time_Value applies the Wrapper Facade pattern [POSA2] and C++ operator overloading to simplify the use of portable time and duration related operations. This class provides the following capabilities:

  • It provides a standardized representation of time that's portable across OS platforms.

  • It can convert between different platform time representations, such as timespec_t and timeval on UNIX, and FILETIME and timeval on Windows.

  • It uses operator overloading to simplify time-based comparisons by permitting standard C++ syntax for time-based arithmetic and relational expressions.

  • Its constructors and methods normalize time quantities by converting the fields in a timeval structure into a canonical format that ensures accurate comparisons between ACE_Time_Value instances.

  • It can represent either a duration, such as 5 seconds and 310,000 microseconds, or an absolute date and time, such as 2001-09-11-08.46.00. Note that some methods, such as operator*=() , are meaningless with absolute times.

The interface for ACE_Time_Value is shown in Figure 3.2 (page 44). As you read this book, keep in mind the points noted in Sidebar 7 (page 46) regarding UML diagrams and C++ code. The key methods of ACE_Time_Value are outlined in the following table:

Method

Description

ACE_Time_Value() set()

Overloaded constructors and methods that convert from various time formats, such as timeval , FILETIME , timespec_t , or long , to a normalized ACE_Time_Value .

sec()

An accessor that returns the seconds portion of an ACE_Time_Value .

usec()

An accessor that returns the microseconds portion of an ACE_Time_Value .

msec()

Converts the sec()/usec() ACE_Time_Value format into millisecond format.

operator+=()

operator-=()

operator*=()

Arithmetic methods that add, subtract, and multiply an ACE_Time_Value .

In addition to the methods shown above, the following binary operators are friends of the ACE_Time_Value class that define arithmetic and relational operations:

Method

Description

operator+()

operator-()

Arithmetic methods that add and subtract two ACE_Time_Value s.

operator==()

operator!=()

Methods that compare two ACE_Time_Value s for equality and inequality.

operator<()

operator>()

operator<=()

operator>=()

Methods that determine relationships between two ACE_Time_Value s.

All ACE_Time_Value constructors and methods normalize the time values they operate on. Normalization reduces microsecond quantities equivalent to one second or more by transferring the seconds value to the secs member, leaving the remaining microseconds value in usecs . For example, normalizing the quantity ACE_Time_Value(1,1000000) will compare equal to the normalized ACE_Time_Value(2) quantity. In contrast, a bitwise comparison of non-normalized objects won't detect their equivalence.

Figure 3.2 The ACE_Time_Value Class
  ACE_Time_Value   + zero : ACE_Time_Value   + max_time : ACE_Time_Value  - tv_ : timeval  + ACE_Time_Value (sec : long, usec : long = 0)  + ACE_Time_Value (t : const struct timeval &)  + ACE_Time_Value (t : const timespec_t  &)  + ACE_Time_Value (t : const FILETIME &)  + set (sec : long, usec : long)  + set (t : const struct timeval &)  + set (t : const timespec_t  &)  + set (t : const FILETIME &)  + sec () : long  + usec () : long  + msec () : long  + operator+= (tv : const ACE_Time_Value &) : ACE_Time_Value &  + operator-= (tv : const ACE_Time_Value &) : ACE_Time_Value &  + operator*= (d : double) : ACE_Time_Value & 

Sidebar 6 describes the differences in the interpretation of ACE_Time_Value when used to represent timeout values for various classes in ACE.

Example

The following example creates two ACE_Time_Value objects whose values can be set via command-line arguments. It then performs range checking to ensure the values are reasonable.

 1 #include "ace/OS.h"   2   3 const ACE_Time_Value max_interval (60 * 60); // 1 hour.   4   5 int main (int argc, char *argv[]) {   6   ACE_Time_Value expiration = ACE_OS::gettimeofday ();   7   ACE_Time_Value interval;   8   9   ACE_Get_Opt opt (argc, argv, e:i:));  10   for (int c; (c = opt ()) != -1;)  11     switch (c) {  12     'e': expiration += ACE_Time_Value (atoi (opt.opt_arg ()));  13          break;  14     'i': interval = ACE_Time_Value (atoi (opt.opt_arg ()));  15          break;  16     }  17   if (interval > max_interval)  18     cout << "interval must be less than "  19          << max_interval.sec () << endl;  20   else if (expiration > (ACE_Time_Value::max_time - interval))  21     cout << "expiration + interval must be less than "  22          << ACE_Time_Value::max_time.sec () << endl;  23   return 0;  24 } 

Sidebar 6: Absolute versus Relative ACE_Time_Value Timeouts

Some ACE classes use relative timeouts, whereas others use absolute timeouts:

  • Relative time semantics

    - ACE IPC wrapper facade I/O methods (Chapter 3 in C++NPv1), as well as higher level framework classes that use them, such as those in the ACE Acceptor-Connector framework (Chapter 7)

    - ACE_Reactor and ACE_Proactor event loop and timer scheduling methods (Chapters 3 and 8)

    - ACE_Process , ACE_Process_Manager , and ACE_Thread_Managerwait() methods (Chapters 8 and 9 in C++NPv1) and

    - Time slice quantum for ACE_Sched_Params (Chapter 9 in C++NPv1).

  • Absolute time semantics

    - ACE synchronizer wrapper facades, such as ACE_Condition_Thread_Mutex and ACE_Thread_Semaphore (Chapter 10 in C++NPv1)

    - ACE timer queue scheduling methods (Chapter 3)

    - ACE_Task methods (Chapter 6) and

    - ACE_Message_Queue methods (Chapter 6), as well as classes based on or that use ACE_Message_Queue , such as those in the ACE Streams framework (Chapter 9) and ACE_Activation_Queue , ACE_Future , and ACE_Future_Set [HJS].

Relative timeouts are often used where the operation (such as an ACE_Thread_Manager::wait() operation) may delay before being able to proceed, but will be called only once. Conversely, absolute timeouts are often used where the operation (such as an ACE_Condition_Thread_Mutex::wait() operation) may be called multiple times via a loop. Use of absolute time avoids the need to recompute the timeout value for each loop iteration [KSS96].

Lines 3 “7 Initialize the ACE_Time_Value objects. By default, an ACE_Time_Value object is initialized to zero.

Lines 9 “16 Parse the command-line arguments using the ACE_Get_Opt class described in Sidebar 8 (page 47).

Lines 17 “22 Perform range checking to ensure the values are reasonable.

Sidebar 7: Displaying ACE Classes and C++ Code

We generally provide a UML diagram and a table that describe the key methods for each ACE C++ class used in this book. Complete class interfaces are available online at http://ace.ece.uci.edu and http://www.riverace.com/docs/.We recommend you keep a copy of the ACE source code handy for quick reference. Complete class implementations and networked logging service examples are available in the ACE source distribution's $ACE_ROOT/ace and $ACE_ROOT/examples/C++NPv2 directories, respectively.

To save space in the book, our UML class diagrams focus on attributes and operations that are used in our code examples. Class diagrams don't show an attributes section when no attributes are directly pertinent to our discussions. We use italics to denote an abstract class or method as follows:

  • A method name set in italics indicates a C++ virtual method that you can reimplement in a derived class.

  • A class name set in italics indicates that you probably need to reimplement one or more of the class's virtual methods to use the class effectively.

If you need a UML overview, we recommend UML Distilled [wKS00].

To further save space, we use some programming shortcuts that aren't used in ACE, such as omitting much of the error-handling code in our C++ examples. Naturally, ACE always checks for error conditions and takes the appropriate action, just as your application software should. Some of our C++ examples also implement methods within the class definition, which we don't do in ACE itself since it clutters class interfaces and slows down compilation. To learn more about ACE's programming guidelines, please see $ACE_ROOT/docs/ACE-guidelines.html .

Ru-Brd


C++ Network Programming
C++ Network Programming, Volume I: Mastering Complexity with ACE and Patterns
ISBN: 0201604647
EAN: 2147483647
Year: 2002
Pages: 65

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net