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.

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).

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.

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 DEC 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().