|
Compaq C++
Compaq C++ Class Library Reference Manual
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()
.
|
|
|