index previous next




file name: psos.h, psos.hpp, psos.cpp
classification: pure simulation
contents: queue management system calls, class CQueue, class CQueueManager
use: simulate pSOS queues in pure simulation


psos.h: Contains the function prototypes of the pSOS system calls needed in the simulation. The file is needed both in pure and in hardware based simulation. In pure simulation, a local file, which only contains the constants and prototypes needed in the simulation, can be used. In hardware based simulation, psos.h is a global include file and should be used instead.


 INT32 q_create(char name[4], INT32 count, INT32 flags, INT32 *qid):
 INT32 q_delete(INT32 qid); INT32 q_ident(char name[4], INT32 node, INT32 *qid):
 INT32 q_receive(INT32 qid, INT32 flags, INT32 timeout, INT32 msg_buf[4]):
 INT32 q_send(INT32 qid, INT32 msg_buf[4]):
 INT32 q_urgent(INT32 qid, INT32 msg_buf[4]):
 INT32 t_mode(INT32 mask, INT32 new_mode, INT32 *old_mode):

In pure simulation, the calls behave as described below. In hardware based simulation, they are part of pSOS, so see the pSOS manual for a description.


global items used in psos.hpp/psos.cpp (except those of psos.h):


local variables defined in the implementation file:

 CQueueManager manager: The queue manager that keeps track of all queues in the system.

Note: since the variable is static, the object is created at some time during the initialization phase of the program, ie., before main() is executed. If you have some other class that works with queues and uses queue system calls in its ctor, you should only use dynamic objects of that class (if you make them static, you have no guarantee that the queue manager is already created when the first queue system call is used).


psos.hpp: Declares two classes CQueue and CQueueManager.

class CQueue: implements a FIFO-Queue.

 struct SLink : Stores an element of the queue, plus a link to the next SLink.

 SLink *first_: The first element in the linked list. If the list is empty, it is NULL.

 SLink *last_: The last element in the list.


 CQueue(): After creation, the queue is empty.

 ~CQueue(): All items in the queue are deleted.

 EBool Empty(): Returns True if the queue is empty, False if it is not.

 INT32 Receive (INT32 data[4]): Removes and returns the first element in the queue. The data is copied into data. The function returns 0 if successful, ERR_NOMSG (see psos.h) if the queue was empty.

 INT32 Send (INT32 data[4], EBool first = False): Puts a copy of the data into the queue. The data is appended if first is False, it is inserted as first item if first is True. The function always returns 0 (success).


class CQueueManager: can create/delete queues, can send/receive messages to/from a particular queue.

 struct SNamedLink: Stores a queue, plus a link to the next SNamedLink.

 SNamedLink *first_: The first element in the linked list. If the list is empty, it is NULL.


 CQueueManager(): At first, no queues exist.

 ~CQueueManager(): Deletes all queues, causing them to delete all items still stored in them.
 INT32 Create (char name[4], INT32 *qid): Creates a queue with the name name and returns a new queue identifier in qid. There is no check for duplicate names (pSOS leaves the implementation free in that case), so take care not to use the same name twice. This implementation simply creates a new queue with the same name, so you can access the queue with its ID, but if you try an Ident() call, you will get the ID of the first queue with that name. The function always returns 0 (success).

 INT32 Delete (INT32 qid): Deletes the queue with the given identifier. All data still stored in the queue is deleted as well. The function returns 0 if successful, ERR_OBJID if no queue with this identifier was found.

 CQueue *Find (INT32 qid): Returns a pointer to the queue with the given identifier. If the queue was not found, NULL is returned.

 INT32 Ident (char name[4], INT32 *qid): Returns the identifier of a queue with this name. If the name is not unique, the first queue with this name is used (that will be the queue that was created first). The function returns 0 if successful, ERR_OBJNF if no queue with this name was found.

 INT32 Receive (INT32 qid, INT32 msg[4]): Removes the first message from the appropriate queue and copies it into msg. The function returns 0 if successful, ERR_OBJID if no queue with this identifier was found, and ERR_NOMSG if the queue was empty.

 INT32 Send (INT32 qid, INT32 msg[4], EBool first = False): Stores a copy of the message in the appropriate queue. The messages is appended if first is False and inserted as first element if first is True. The function returns 0 if successful, ERR_OBJID if no queue with this identifier was found.


psos.cpp: Defines the methods of CQueue and CQueueManager.


 INT32 q_create(char name[4], INT32 count, INT32 flags, INT32 *qid): Creates a queue, returns the ID in qid. Calls CQueueManager::Create(), so the text about duplicate names applies here as well. Parameters count and flags are ignored. The function always returns 0 (success).

 INT32 q_delete(INT32 qid): Deletes the queue and all data still stored in it. The function returns 0 if successful, ERR_OBJID if no queue with this identifier was found.

 INT32 q_ident(char name[4], INT32 node, INT32 *qid): Searches for a queue with the name, returns the identifier of the first queue that was found. Parameter node is ignored. The function returns 0 if successful, ERR_OBJNF if no queue with this name was found.

 INT32 q_receive(INT32 qid, INT32 flags, INT32 timeout, INT32 msg_buf[4]): Removes the first message from the queue and puts it into msg_buf. Parameters flags and timeout are ignored, the call behaves as if flags=1 and timeout=0 (No Wait). The function returns 0 if successful, ERR_OBJID if no queue with this identifier was found, ERR_NOMSG if the queue was empty.

 INT32 q_send(INT32 qid, INT32 msg_buf[4]): Puts a new message into the queue (as last element). The function returns 0 if successful, ERR_OBJID if no queue with this identifier was found.

 INT32 q_urgent(INT32 qid, INT32 msg_buf[4]): Puts a new message into the queue (as first element). The function returns 0 if successful, ERR_OBJID if no queue with this identifier was found.

 INT32 t_mode(INT32 mask, INT32 new_mode, INT32 *old_mode): Asserts that old_mode is not NULL, and sets its value to 0xFFFFF1FF (for testing purposes). Apart from that the call has no effect. The call is important in hardware based simulation, if data structures are accessed by more than one module. The function always returns 0 (success).


last modified: Fri Feb 5 18:56:32 1999