United States

Compaq C++

# Compaq C++
Class Library Reference Manual

Previous | Contents | Index

# qhead class

> Abstraction for the head of a list of items arranged in a first-in, first-out singly linked list.

## Header

> `#include <task.hxx>`

> Alternative Header

> `#include <task.h>`

## Declaration

>     class qhead: public object
>     {
>     public:
>                   qhead(qmodetype modetype = WMODE, int size = 10000);
>                   ~qhead();

>         qhead     *cut();
>         object    *get();
>         int       putback(object *new_queue_element);
>         int       rdcount();
>         int       rdmax();
>         qmodetype rdmode();
>         void      setmode(qmodetype modetype);
>         void      setmax(int size);
>         void      splice(qtail *delete_tail);
>         qtail     *tail();

>         int       pending();
>         void      print(int verbosity, int internal_use = 0);
>         objtype   o_type();
>     };

## Description

> This class provides facilities for taking objects off a queue. A queue is a data structure with an associated list of objects of the `object` class, or a class derived from the `object` class in first-in, first-out order. All access to a queue is through either the attached `qhead` or attached `qtail` object. You create a queue by creating either a `qhead` or a `qtail` object. The other end of the queue is created automatically. You can then obtain a pointer to the tail with the `qhead::tail` function.

> Objects have definitions for when they are ready and pending (not ready). The `qhead` objects are ready when the queue is not empty and pending when the queue is empty.

## Exception Handling

> When a run-time error occurs, the appropriate error code from the following table is passed to the `object::task_error()` function:

> Value | Error Description
> --- | ---
> `E_BACKFULL` | Cannot putback an object into a full queue
> `E_BACKOBJ` | Cannot putback an object into a queue if the object is on another queue
> `E_GETEMPTY` | Cannot get an object from an empty queue
> `E_QDEL` | Cannot delete a queue that has an object in the queue
> `E_STORE` | Cannot allocate more memory

## Constructors and Destructors

> ### qhead(qmodetype modetype = WMODE, int size = 10000)

> Constructs a `qhead` object. The modetype argument determines what happens when an object of the `qhead` class is pending. The choices are `WMODE` (wait mode), `EMODE` (error mode), or `ZMODE` (0 mode); the default is `WMODE` (see the `get()` function for more information). The size argument sets the maximum length of the queue attached to a `qhead` object; the default is 10,000.

> The maximum size of the queue does not affect the amount of memory occupied by the queue when the queue is empty.

> ### ~qhead()

> Deletes a `qhead` object.

## Member Functions

> ### qhead *cut()

> Splits a queue into two queues. One queue has a new `qhead` object, which the return value points to, and the original `qtail` object; it contains the objects from the original queue. The other queue has the original `qhead` object and a new `qtail` object; this queue is empty. You can use this function to insert a filter into an existing queue without changing the queue's appearance to functions that access the ends of the queue, and without halting the flow through the queue of objects.

> ### object *get()

> Returns a pointer to the `object` at the head of the queue when the queue is not empty. The object is removed from the queue. If the queue is empty, behavior depends on the mode of the `qhead` object. In `WMODE` , a `task` that executes `qhead::get()` on an empty queue suspends until that queue is not empty. In `EMODE` , executing `qhead::get()` on an empty queue causes a run-time error. In `WMODE` , executing `qhead::get()` on an empty queue returns the `NULL` pointer instead of a pointer to an `object` .

> ### virtual objtype o_type()

> Returns `object::QHEAD` .

> ### int pending()

> Specifies that `get` operations on a queue must wait until an object is put in the queue. It returns a nonzero value if the queue attached to a `qhead` object is empty; otherwise, it returns 0.

> ### void print (int verbosity, int internal_use = 0)

> Prints a `qhead` object on `cout` . The verbosity argument specifies the information to be printed. For more information, see the enum Print Function Arguments section under Global Declarations for the task package. Do not supply a value for the internal_use parameter.

> ### int putback(object *new_queue_element)

> Inserts at the head of the queue the `object` that the new_queue_element argument points to, and returns a value of 1 on success. This lets the `qhead` object operate as a stack (hence, the name `putback` ). Space must be available in the queue for it to succeed. Calling `qhead::putback()` for a full queue causes a run-time error in both `EMODE` and `WMODE` and returns `NULL` in `ZMODE` .

> ### int rdcount()

> Returns the current number of objects in the queue attached to a `qhead` object.

> ### int rdmax()

> Returns the maximum length of the queue.

> ### qmodetype rdmode()

> Returns the current mode of a `qhead` object, which can be `EMODE` , `WMODE` , or `ZMODE` .

> ### void setmode(qmodetype modetype)

> Sets the mode of a `qhead` object to modetype, which can be `EMODE` , `WMODE` , or `ZMODE` .

> ### void setmax(int size)

> Sets size as the maximum length of the queue attached to a `qhead` object. You can set size to a number less than the current number of objects of the `object` class, but that means you cannot put any more objects of the `object` class on the queue until the length of the queue has been reduced below the limit you set.

> ### void splice(qtail *delete_tail)

> Forms a single queue by appending a queue attached to a `qhead` object onto the queue referenced in the argument. Typically, this reverses the action of a previous `qhead::cut()` function. The extra `qhead` and `qtail` objects are deleted. Waiting tasks resume execution if merging the two creates a nonempty queue (if the task was trying to get) or an empty queue (if the task was trying to put).

> ### qtail *tail()

> Creates a `qtail` object for the queue attached to a `qhead` object (if none exists) and returns a pointer to the new `qtail` object.

# qtail class

> Abstraction for the tail of a list of items in a first-in, first-out singly linked list.

## Header

> `#include <task.hxx>`

> Alternative Header

> `#include <task.h>`

## Declaration

>     class qtail: public object
>     {
>         friend class qhead;

>     public:
>                   qtail(qmodetype modetype = WMODE, int size = 10000);
>                   ~qtail();

>         qtail     *cut();
>         qhead     *head();
>         int       put(object *new_queue_element);
>         int       rdspace();
>         int       rdmax();
>         qmodetype rdmode();
>         void      setmode(qmodetype modetype);
>         void      setmax(int size);
>         void      splice(qhead *delete_head);

>         int       pending();
>         void      print(int verbosity, int internal_use = 0);
>         objtype   o_type();
>     };

## Description

> This class provides facilities for putting objects into a queue. A queue is a data structure with an associated list of objects of the `object` class, or a class derived from the `object` class in first-in, first-out order. All access to a queue is through either the attached `qhead` or `qtail` object. You create a queue by creating either a `qhead` or a `qtail` object. The other end of the queue is created automatically. You can then obtain a pointer to the head with the `qtail::head` function.

> Objects have definitions for when they are ready and pending (not ready). The `qtail` objects are ready when the queue is not full and pending when the queue is full.

## Exception Handling

> When a run-time error occurs, the appropriate error code from the following table is passed to the `object::task_error()` function:

> Value | Error Description
> --- | ---
> `E_PUTFULL` | Cannot put an object into a full queue
> `E_PUTOBJ` | Cannot put an object into queue if the object is on another queue
> `E_QDEL` | Cannot delete a queue that has an object in the queue
> `E_STORE` | Cannot allocate more memory

## Constructors and Destructors

> ### qtail(qmodetype modetype = WMODE, int size = 10000)

> Constructs a `qtail` object. The modetype argument specifies the mode (set by the constructor) that controls what happens when an object of the `qtail` class is pending. The choices are `WMODE` (wait mode), `EMODE` (error mode), or `ZMODE` (0 mode); `WMODE` is the default. (See the `put()` function for more information.) The size argument specifies the maximum length of the queue attached to a `qhead` object; the default is 10,000.

> The maximum size of the queue does not affect the amount of memory occupied by the queue when the queue is empty.

> ### ~qtail()

> Deletes a `qtail` object.

## Member Functions

> ### qtail *cut()

> Splits a queue into two queues. One queue has a new `qtail` object (to which the return value points) and the original `qhead` object; it contains the objects from the original queue. The other queue has the original `qtail` object and a new `qhead` object; this queue is empty. You can use this function to insert a filter into an existing queue, without changing the queue's appearance to functions that access the ends of the queue, and without halting the flow through the queue of objects.

> ### qhead *head()

> Creates a `qhead` object for the queue attached to a `qtail` object (if none exists) and returns a pointer to the new `qhead` object.

> ### virtual objtype o_type()

> Returns `object::QTAIL` .

> ### int pending()

> Specifies that get operations on a queue must wait until an object is put in the queue. It returns a nonzero value if the queue is empty; otherwise, it returns 0.

> ### virtual void print(int verbosity, int internal_use = 0)

> Prints a `qtail` object on `cout` . The verbosity argument specifies the information to be printed. For more information, see the enum Print Function Arguments section under Global Declarations for the task package. Do not supply a value for the internal_use parameter.

> ### int put(object *new_queue_element)

> Adds the `object` denoted by the new_queue_element argument to the tail of the queue attached to a `qtail` object; returns a value of 1 on success. If the queue is full, the behavior depends on the mode of the `qtail` object. In `WMODE` , an object of class `task` that executes `qhead::put()` on a full queue suspends until that queue is not full. Calling `qhead::put()` for a full queue causes a run-time error in `EMODE` and returns `NULL` in `ZMODE` .

> ### int rdspace()

> Returns the number of `object` objects that can be inserted into the queue before it becomes full.

> ### int rdmax()

> Returns the maximum length of the queue.

> ### qmodetype rdmode()

> Returns the current mode of a `qtail` object, which can be `EMODE` , `WMODE` , or `ZMODE` .

> ### void setmode(qmodetype modetype)

> Sets the mode of a `qtail` object to modetype, which can be `EMODE` , `WMODE` , or `ZMODE` .

> ### void setmax(int size)

> Sets size as the maximum length of the queue. You can set size to a number less than the current number of objects of the `object` class, but that means you cannot put any more objects of the `object` class on the queue until the length of the queue has been reduced below the limit you set.

> ### void splice(qhead *delete_head)

> Forms a single queue by appending a queue attached to a `qtail` onto the queue referenced in the argument. Typically, this reverses the action of a previous `qtail::cut()` . The extra `qhead` and `qtail` objects are deleted. Waiting tasks resume execution if merging the two queues creates a nonempty queue (if the task was trying to get) or an empty queue (if the task was trying to put).

# randint class

> Objects of the `randint` class generate uniformly distributed random numbers.

## Header

> `#include <task.hxx>`

> Alternative Header

> `#include <task.h>`

## Declaration

>     class randint
>     {
>     public:
>                randint(long seed=0);
>         int    draw();
>         float  fdraw();
>         void   seed(long seed);
>     };

## Description

> Objects of this class generate uniformly distributed random numbers. Each random-number generator object produces a sequence that is independent of other random-number generator objects.

## Constructor

> ### randint(long seed)

> Constructs an object of the `randint` class. The seed argument is used as the seed and is optional. Different seeds produce different sequences of generated numbers; not all seeds produce useful sequences.

## Member Functions

> ### float fdraw()

> Returns the next random number generated by the object. The number is a floating-point value in the range 0 to 1.

> ### int draw()

> Returns the next random number generated by the object. The number is an integer value in the range from 0 to `RAND_MAX` , which is defined in the ANSI C header, `stdlib.h` .

> ### void seed(long seed)

> Reinitializes the object with the seed seed.

## Example

    extern "C" {
    #include <stdlib.h>
    }
    #include <task.hxx>
    #include <iostream.hxx>
    main()
     {
         randint gen;
         int i=0;
         float sum;
         for (i=0; i<1000; i++)
              sum += gen.fdraw();
         cout<<"Average is " << sum/1000. << "\n";
         return EXIT_SUCCESS;
     }

> This example prints the average of 1000 floating-point random numbers.

# sched class

> Responsible for scheduling and for the functionality common to `task` and `timer` objects.

## Header

> `#include <task.hxx>`

> Alternative Header

> `#include <task.h>`

## Declaration

>     class sched: public object
>     {
>     public:
>         enum statetype
>         {
>             IDLE = 1,
>             RUNNING = 2,
>             TERMINATED = 4
>         };

>     protected:
>                      sched();

>     public:
>         static task  *clock_task;
>         static PFV   exit_fct;

>         void         cancel(int result);
>         int          dont_wait();
>         sched        *get_priority_sched();
>         int          keep_waiting();
>         statetype    rdstate();
>         long         rdtime();
>         int          result();

>         int          pending();
>         virtual void print(int verbosity, int internal_use = 0);
>         virtual void setwho(object *alerter);

>         static long  get_clock();
>         static sched *get_run_chain();
>         static int   get_exit_status();
>         static void  set_exit_status(int);
>         static void  setclock(long);
>     };

>     #ifdef CXXL_DEFINE_CLOCK
>     #define clock (sched::get_clock())
>     #endif
>     #define run_chain (sched::get_run_chain())

## Description

> This class provides facilities for checking on the state of a task, manipulating the simulated clock, canceling a task, and checking on the result of a task.

> You can create instances of classes derived from the `sched` class, but you cannot create instances of the `sched` class itself.

## Exception Handling

> When a run-time error occurs, the appropriate error code from the following table is passed to the `object::task_error()` function:

> Value | Error Description
> --- | ---
> `E_CLOCKIDLE` | Cannot advance the clock when the clock_task is `RUNNING` or `TERMINATED`
> `E_NEGTIME` | Cannot delay a negative amount of time
> `E_RESOBJ` | Cannot resume a task or timer if it is already on another queue
> `E_RESRUN` | Cannot resume a `RUNNING` task
> `E_RESTERM` | Cannot resume a `TERMINATED` task
> `E_SCHOBJ` | Cannot use class `sched` other than as a base class
> `E_SCHTIME` | Cannot execute something at a time that has already passed
> `E_SETCLOCK` | Cannot set the clock after it has advanced past 0

## Member Data

> ### static task *clock_task

> Points to the task clock if one exists.

> ### static PFV exit_fct

> Points to the exit function if one exists.

## Constructor

> ### sched()

> Constructs a `sched` object initialized to the `IDLE` state and delay 0.

## Member Functions

> ### void cancel(int result)

> Puts an object into the `TERMINATED` state without suspending the caller (that is, without invoking the scheduler); sets the result of the object to result.

> ### int dont_wait()

> Returns the number of calls to `keep_waiting()` , minus the number of calls to the `dont_wait()` function, excluding the current call. The return value of this function should equal the number of objects of the `object` class waiting for external events before the current `dont_wait()` call.

> ### long get_clock()

> Returns the value of the clock in simulated time units.

> ### int get_exit_status()

> Returns the exit status of the task program. When a task program terminates successfully (without calling `task_error` ), the program calls `exit(i)` where i is the value passed by the last caller of `sched::set_exit_status()` .

> ### sched *get_priority_sched()

> Returns a pointer to a system task's `interrupt_alerter` if the system gets an awaited signal. If no interrupt occurs, this function returns 0.

> ### sched *get_run_chain()

> Returns a pointer to the run chain, the linked list of ready objects belonging to classes derived from the `sched` class ( `task` and `timer` objects).

> ### int keep_waiting()

> Keeps the scheduler from exiting when no tasks exist that can be run (an external event could enable an `IDLE task` to be run). This function should be called when the user program creates an object that waits for an external event. Afterward, when such an object destructs, a call should go to the `dont_wait()` function. The `keep_waiting()` function returns the number of calls (not counting the current call) minus the number of calls to the `dont_wait()` function.

> ### int pending()

> Returns 0 if the object is in the `TERMINATED` state; otherwise, it returns a nonzero value.

> ### virtual void print(int verbosity, int internal_use = 0)

> Prints a `sched` object on `cout` . The verbosity argument specifies the information to be printed. For more information, see the enum Print Function Arguments section under Global Declarations for the task package. Do not supply a value for the internal_use parameter.

> ### statetype rdstate()

> Returns the state of the object: `RUNNING` , `IDLE` , or `TERMINATED` .

> ### long rdtime()

> Returns the simulated clock time at which to run the object.

> ### int result()

> Returns the result of a `sched` object (as set by the `task::resultis()` , `task::cancel()` , or `sched::cancel()` function). If the object is not yet `TERMINATED` , the calling `task` suspends and waits for the object to terminate. A `task` calling `result()` for itself causes a run-time error.

> ### void setclock(long new_clock)

> Initializes the simulated clock to a time specified by the new_clock argument. You can use this function once before the simulated clock has advanced without causing a run-time error. To advance the clock after the initial setting, call the `task::delay` function.

> ### void set_exit_status(int new_exit_status)

> Sets the exit status of the task program. When a task program terminates successfully (without calling `task_error` ), the program calls `exit(i)` , where i is the value passed by the last caller of `sched::set_exit_status()` .

> ### virtual void setwho(object *alerter)

> Records which object alerted the object. The alerter argument should represent a pointer to the `object` that caused the task package to alert the `sched` .

## Macros

> The C++ Class Library supplies the following macros for compatibility with older C++ class library implementations:

> > ### clock

> > Calls `sched::get_clock()` . For this macro to be defined, you must define `CXXL_DEFINE_CLOCK` on the command line when invoking the compiler, or in your source code before including the task package header.

> > ### run_chain

> > Calls `sched::get_run_chain()` .

Previous | Next | Contents | Index

privacy and legal statement