C/C++ User's Journal & Windows Developer's Journal Tools

home *** CD-ROM | disk | FTP | other *** search

/ C/C++ User's Journal & Wi…eveloper's Journal Tools / C-C__Users_Journal_and_Windows_Developers_Journal_Tools_1997.iso / smxdemo / smxpp / smxspec.doc < prev next >

Wrap

Text File | 1993-02-06 | 40.0 KB | 1,418 lines

1-31-93 smx++ Design Specification 1.0 Introduction smx++ is a C++ class library which sits on top of smx. The smx++ API is designed to mirror smx yet be simpler and easier to use. In most cases, smx++ methods call their smx counterparts for system services. A chief objective of smx++ is to provide a simpler API which meets most user requirements. As a consequence, several smx features and functions have been left out or are accessible only in a restricted manner (see Limitation section). Where this becomes a problem, the user can make smx calls directly. (He also, of course, can create his own system objects.) The smx++ classes contain pointers to the control blocks they use. This is to remove the burden of declaring control blocks from the user. With smx++ the user will use the names of objects instead of the names of control block handles (pointers). Since classes do not incorporate control blocks, the same control block management scheme can be used for smx and smx++. This has the benefit that the user can both use smx++ objects and make smx calls directly (but not for the same object). Because of the close relationship of smx++ to smx, method descriptions herein are intentionally brief. Refer to the smx Reference Manual for detailed information. NOTE: Certain enhancements to smx (e.g. fully dynamic objects) are necessary to implement this specification. It has been decided to allow these to go forward independently of the current version (v2.x) of smx. The underlying version of smx will be identified as V3.0. Versions will be merged at a later time in V3.x. 1 2.0 Classes smx++ is made up of nine base classes. The following is a list of the base classes: Counter, Event, Exchange, SIOBus, Message, Block Pool, Semaphore, Task, and Process. 2.1 Class hierarchy Base Class 1st Derived Class 2nd Derived Class Counter SIOBus Bucket block device drivers Pipe character device drivers Exchange Normal Exch Pass Exch Resource Exch Message Block Pool FarHeap Pool NearHeap Pool Semaphore Task Event Process 3.0 Counter Class The Counter class is used to count the number of times an event happens. See smx manual on event queues. 3.1 Counter Data Members The Counter class has only one data member, the counter control block pointer. It is a private data member and is only used by the Counter methods. ECB_PTR CounterCBP; 2 3.2 Constructors The Counter class has only one constructor and it takes no parameters. It will call the create_eq smx function and store the ECB_PTR as its private data member. void Counter(); void Counter(ECB_PTR p); 3.3 Methods The Counter class has five methods: Signal, Count, CountStop, ClearQ, and QSize. They perform the same function as their smx counterparts. Method declarations: BOOLEAN Signal(); BOOLEAN Count( word count, word TimeOut=INF ); BOOLEAN CountStop( word count, word TimeOut=INF ); BOOLEAN ClearQ(); int Qsize(); 3.3.1 Signal Signal will signal the system that an event has just occurred. It takes no parameters and calls its smx counterpart passing it the handle in counterCBP. 3.3.2 Count Count suspends the current task for a specified number of signals. Count takes two parameters: count and timeout. The count parameter is the number of signals before the task will resume. Timeout, which is usually not required because it has a default value of infinite, will resume the task at the end of the timeout period if it has not already been resumed. 3.3.3 CountStop CountStop works like Count except that the task is first stopped. 3.3.4 ClearQ This method works like its smx counterpart. 3.3.5 Qsize This method works like its smx counterpart. 3 3.4 Destructor The Counter destructor deletes the event instance and sends any system resource back. This includes the ECB_PTR that was obtained by the constructor and the event control block. 4.0 SIOBus Class The SIOBus (Software Input/Output Bus) is an abstract base class. It is used for system communication with block and character devices. The intent of the SIOBus is to provide a uniform data interface for all device drivers. (A uniform control interface will be added in the future.) The SIOBus class has two methods which are pure virtual methods. This reduces the number of methods that other classes must implement. Two classes derived from the SIOBus are generic drivers: (1) bucket for block-oriented devices (2) byte pipe for character-oriented devices A word pipe may be implemented in the future. Actual device drivers will be derived by users from the generic device drivers (bucket and pipe). Note that a device driver is uni-directional. Hence, two are required for a bi-directional device. 4.1 Data Members VOID_PTR SIOXCBP; 4.2 Constructors The SIOBus class is an abstract class and does not use a constructor. 4.3 Methods The SIOBus class has two methods, GetChar and PutChar. They are pure virtual methods which must be defined in the derived classes. Method Declarations: int GetChar()=0; BOOLEAN PutChar( char achar )=0; 4 4.3.1 GetChar GetChar is a pure virtual method which is used to get a character from an SIOBus object. The derived classes will have their own interpretations of it. 4.3.2 PutChar PutChar is a pure virtual method which is used to put a character on a SIOBus. The derived classes will have their own interpretations of it. PutChar accepts the character to be put as its parameters. 4.4 Destructor Since the SIOBus is an abstract class, it does not require a destructor. 4.5 Bucket Class The bucket class is used in the same manner as an smx bucket. It is derived from the SIOBus class. In smx++ it is intended that the user take the bucket class one step further. The user should derive his particular class from the bucket class to communicate with his custom hardware. He will do this by creating his own constructor that will initialize his hardware and a destructor that will shutdown his hardware. Also, the two methods PutChar and Getchar should be overloaded to interface with his hardware. 4.5.1 Data Members None 4.5.2 Constructors The bucket class has two constructors. The first takes no parameters; it calls the smx function create_cx(BUCKET). The second constructor takes a size parameter. It creates a bucket and a message of the specified size, from the near heap and sends the message to the bucket. void Bucket(); void Bucket( word size); void Bucket( CXB_PTR p); 4.5.3 Methods The bucket class defines the two virtual methods GetChar and PutChar which it inherits from the SIOBus class. Theses methods 5 are protected so they can be used only in device drivers. Method Definitions: int GetChar(); BOOLEAN PutChar( char achar ); 4.5.3.1 GetChar GetChar is used to get a character from a bucket. smx implements this as a C macro. The GetChar method will be implemented as an inline method. It takes no parameters and returns an int which is the next character. This method is used only within device drivers. It is not used for system communication via the SIOBus (see the Message class for this). 4.5.3.2 PutChar PutChar is used to put a character into a bucket. It is implemented in smx as a C macro and will be an inline method in smx++. It takes a character parameter and returns a BOOLEAN. This method is used only within device drivers and is not used for system communication. 4.5.4 Destructor The bucket class destructor releases BucketCBP and the control block for the bucket. If the Bucket is holding a message, a pool message is returned to its pool and a non-pool message is deleted. 4.6 Pipe Class The pipe class is used in the same manner as an smx pipe. It is derived from the SIOBus class. In smx++ the pipe class is intended to be used by the user in the same manner that the bucket class was. The user should derive his own class reflecting the personality of his hardware. Again all functions will be overloaded and the constructor and destructor will do the initializing and closing of the device. 4.6.1 Data Members None 6 4.6.2 Constructors The constructor creates a pipe and a message of the specified size from the near heap. It attaches the message to the pipe for use as its buffer. void Pipe( word size ); void Pipe( CXP_PTR p ); 4.6.3 Methods In addition to GetChar, and PutChar, which it inherits from the base class, the pipe class defines four more methods. GetChar and PutChar are protected methods. The others are public. Method Declaration: int GetChar(); BOOLEAN PutChar( char achar ); int PGetChar( word TimeOut=INF ); int PGetCharStop( word TimeOut=INF ); BOOLEAN PPutChar( char achar, word TimeOut=INF ); BOOLEAN PPutCharStop( char achar, word TimeOut=INF ); 4.6.3.1 GetChar smx++ implements this in the same way smx implements PGET_CHAR. This is the fast version for smx. It will be an inline method in smx++. Like its smx counterpart it takes no parameters and returns an int. This is a protected method for use by device drivers, only. 4.6.3.2 PutChar smx++ implements this in the same way smx implements PPUT_CHAR. This is the fast version for smx. It will be an inline method in smx++. This method accepts a character to be put into the pipe. It will return a BOOLEAN to indicate if the operation was successful. This is a protected method for use by device drivers, only. The return value works like the bucket GET_CHAR in the smx Reference Manual. 4.6.3.3 PGetChar This method calls the smx function, pget_char. It takes a timeout parameter which has a default value of infinite. It returns an int, which contains the character. 7 4.6.3.4 PGetCharStop GetCharStop works just like the PGetChar method. The only difference is that it stops the task first. 4.6.3.5 PPutChar This method calls the smx function, pput_char. It accepts character and timeout parameters. The timeout parameter has a default value of infinite. 4.6.3.6 PPutCharStop The putcharstop method works just like the putchar method except that it stops the task first. 4.6.4 Destructor The pipe class destructor releases PipeCBP and the pipe control block. It also deletes the pipe's buffer. (Pipe buffers are always non-pool near messages). A task waiting at the pipe is resumed. 5.0 Exchange Class The exchange class is the base class for the normal, pass and resource exchange classes. It defines the basic methods for them. There should not be an instance of the exchange class since it is intended to be just a base class. The methods are defined here to centralize code location and reduce coding effort. 5.1 Data Members The exchange has one data member which is the exchange control block pointer. It is a private member and is only used by member functions. XCB_PTR XchgCBP; 5.2 Constructors Since the exchange is a base class and not intended to have an instances there is no constructor. 8 5.3 Methods The exchange class has two methods: ClearQ and QSize. Method Declaration BOOLEAN ClearQ(); int QSize(); 5.3.1 ClearQ This method works like its smx counterpart. 5.3.2 QSize This method also works like its smx counterpart. 5.4 Destructor The exchange class does not define a destructor. Since it is a base class and it is intended that no instances of it should exist. 5.5 Normal Exchange Class The normal exchange class is derived from the exchange class. It serves the same function as its smx counterpart. 5.5.1 Data Members There are no data members. They are all defined in the base class. 5.5.2 Constructors There are two constructors for the normal exchange class. The normal constructor takes two variable length parameters: the task priority limits and the message priority limits. The larger number of limits dictates the number of queue control blocks required. The other constructor is the copy constructor. It is used to create a twin exchange. The new exchange will have the same limits as the old exchange. void NrmXchg( word tplimN, ... ); void NrmXchg( XCB_PTR p ); 9 5.5.3 Methods No additional methods are defined for this class. 5.5.4 Destructor The destructor releases the XchgCBP and the queue control blocks. 5.6 Pass Exchange The pass exchange is built like the normal exchange. It also functions like its smx counterpart. 5.7 Resource Exchange The resource exchange is built like the normal exchange. Resource exchanges function as the centers of message pools. When a message is sent to a resource exchange, it is stamped with the resource exchange i.d. and thereafter is a "pool" message. The advantage of pool messages is that they are fast to obtain and release. ClearQ will resume waiting tasks, but it cannot remove messages. 6.0 Message Class The message class is used to hold a message that is in use by the application code. It has the methods to send, receive, create, and delete messages. It should be noted that an instance of the class can exist without holding a message. A message consists of a mcb and a data block. The mcb contains a pointer to the data block. The message class is a friend class to the exchange and SIOBus classes. It needs this friendship to have access to the control block pointers of each class. The message class is a general class that can hold any type of message. It is designed this way because there is no way to know what type of message you will be holding. This is due to the fact that a resource exchange can contain messages from both heaps and a pool at the same time. 6.1 Data Members The message class has one private data members, the message control block pointer, which is used by smx. Message objects are said to be either "holding" or "not holding" a message. This complexity arises from the fact that messages transcend the scopes of the code threads (i.e. "tasks") which use them. 10 Messages are sent from one thread to another. MCB_PTR MsgCBP; Boolean Holding; 6.2 Constructors The message class has three constructors. The first, creates only an instance. The second creates an instance and a message. (i.e. it creates an mcb and gets a data block from the smx near or far heap). The third constructor is the copy constructor. It will create a new instance and, if the old one is holding, create a new message and copy over data. void Message(); void Message( word Blksize, HEAPTYPE near Heap ); void Message( MCB_PTR p ); The first constructor creates a non-holding message object which is ready to receive from an exchange. The second constructor can be used to initially create messages. If one of these messages is sent to a resource exchange, it becomes a member of the message pool defined by that resource exchange. 6.3 Methods Method Descriptions: BOOLEAN BumpMsg( word priority ); BOOLEAN Send( const Xchg& xchg ); BOOLEAN Receive( const Xchg& xchg, word TimeOut=INF); BOOLEAN ReceiveStop( const Xchg& xchg, word TimeOut=INF ); void far* Contents(); BOOLEAN Put( const SIOBus& xchg ); BOOLEAN Get( const SIOBus& xchg ); BOOLEAN Holding(); BOOLEAN Create( word size, BOOLEAN ht=NEAR ); BOOLEAN Create( word size, const ResExch& rxchg HeapType ht=NEAR, word num=1 ); BOOLEAN Delete(); 11 6.3.1 Send The send method is used to send the message to an exchange and takes a message exchange its parameter. If the message object is not holding, the send method aborts and returns a NOT_HOLDING error. The second type of send takes an additional parameter which is the priority of the message. (This send replaces the smx function bump_msg). If the message is already at the specified destination, it is merely requeued. 6.3.2 Receive The receive method is used to get a message from an exchange and takes an exchange reference and a timeout as parameters. The timeout parameter has a default value of infinite. If the message object is already holding a message, receive is aborted and a HOLDING error is reported. 6.3.3 Receive Stop Receive stop works just like the receive method except that the task is first stopped. 6.3.4 Contents This method is used to get the contents of the message. It returns a void far pointer to the data blocks. Its smx counterpart is msg->mv. If the message instance is not holding, the method will return NULL. The contents method assume the worst case return type of far pointer. It is necessary to do this since it is impossible to predict what type of message we will be holding at any given time. 6.3.5 Put Put is used to send a message to a SIOBus. It Takes a SIOBus reference as a parameter. If you try to use a message that is not from the near heap as a SIOBus buffer you will receive a WRONG_MCB_TYPE error and return a false condition. This is due to the fact that SIOBus's can only accept a near messages as a buffer. See the smx manual for further details. 6.3.6 Get Get is used to get a message from a SIOBus. It Takes a SIOBus reference as a parameter. See the smx manual for further details. 12 6.3.7 Holding This method is used to indicate if a class instance is holding a message. It tests the MCB_PTR for NULL and if it is NULL, Holding will return a false condition indicating that the class instance is not holding a message. A true response indicates the class instance is holding a message. 6.3.8 Create The create message method is used to create a message from the far heap. It comes in two types. The first one takes a size and the heaptype as parameters. It just creates a message and prepares it for use. The second create message method, in addition to the above parameters, takes a resource exchange reference and number of blocks as parameters. It is used to create multiple messages and send them to a resource exchange. It will send the previous message to the exchange before the next one is created. With both versions of the create message method, if the instance is holding a message when the method is used a HOLDING error will be reported. 6.3.9 Delete The deleted message method will delete a message that is being held by a message instance. A heap message is freed and a pool message is sent back to its resource exchange. If the message instance is not holding this method has no affect. 6.4 Destructor The message class destructor releases the MsgCBP. If the message object is holding a message, the message is deleted (i.e. its mcb is released and its data block is freed to the appropriate heap.) 7.0 Block Pool Class The memory pool class is used to control access to block memory pools. It is the base class for the near heap and far heap pools. There should not be an instance of the memory pool class. 7.1 Data Members The only data member is the pointer to the pool control block. It is protected. PCB_PTR PoolCBP; 13 7.2 Constructors The memory pool class does not have a constructor since it is a base class and there should not be an instance of it. 7.3 Methods The memory pool class defines two methods. Method Descriptions: BCB_PTR Get(); BOOLEAN Release( BCB_PTR bp ); 7.3.1 Get The Get method works just like its smx counterpart. It takes no parameters and returns a block control block pointer. 7.3.2 Release The Release method works just like its smx counterpart. It accepts a block control block as a parameter and returns a BOOLEAN for testing. 7.4 Destructor Since the memory pool is a base class it does not have a destructor and there will not be an instance of it. 7.5 Far Heap Memory Pool Class The far heap memory pool is derived from the memory pool. It has no additional methods. As its name implies it get its memory from the far heap. 7.5.1 Constructor The far heap memory pool has only one constructor. It accepts the number of blocks and block size as parameters. It will create a memory pool from the far heap. void FarHeapPool( word NumBlks, word BlkSize ); void FarHeapPool( PCB_PTR p ); 7.5.2 Destructor The destructor releases all the memory used by the pool back to the system. If any block is in use (i.e. has an owner) operation is aborted and a OBJECT_IN_USE error is reported. 14 7.6 Near Heap Memory Pool Class The near heap memory pool works just like the far heap memory pool except it gets its memory from the near heap. 8.0 Semaphore Class The semaphore class is used to create a semaphore with a specified threshold and one or more task priority levels. This class is the base class with no other class derived from it. 8.1 Data Members The only data member for the semaphore class is the pointer to the semaphore control block. It is a private data member. SCB_PTR SemCBP; 8.2 Constructors The semaphore class has two constructors: a regular constructor and a copy constructor. The regular constructor takes the same parameters as the create_sem() smx function. It is used to create a semaphore from scratch. One queue control block is required per priority level. The copy constructor will create a new semaphore with the same parameters as the original. void Sem( word thres, word tplimN, ... ); void Sem( SCB_PTR p ); 8.3 Methods The semaphore class has five methods. These methods are similar to their smx counterparts. BOOLEAN Signal(); BOOLEAN Test( word TimeOut=INF ); BOOLEAN TestStop( word TimeOut=INF ); BOOLEAN ClearQ(); int QSize(); 8.3.1 Signal The signal method is used to increment a semaphore's internal counter. It takes no parameters and return a BOOLEAN. 15 8.3.2 Test The test method is used to test if a semaphore's internal counter has reached or exceeded its threshold. When test passes, the internal counter is reduced by the threshold. Test accepts a timeout parameter which has a default value of infinite. 8.3.2 TestStop TestStop works like Test except TestStop first stops the test. 8.3.3 ClearQ This method works like its smx counter part. 8.3.4 QSize This method works like its smx counter part. 8.4 Destructor The semaphore class destructor releases semCBP and the queue control blocks. Tasks waiting on this semaphore are resumed with FALSE return values. 9.0 Task Class The task class defines the API for working with tasks. The methods in this class are similar to their smx counterparts. 9.1 Data Members The only data member for the task class is the task control block pointer. It is a private member. TCB_PTR TaskCBP; 9.2 Constructors The task class has two constructors: a regular constructor and a copy constructor. The regular constructor accepts the same parameters as the create_task smx function. It is used to create a task from scratch. The copy constructor creates a new task with the same parameters as the original. void Task( const cdecl void(*TaskMain), byte priority, word StackSize=0 ); void Task( TCB_PTR p ); 16 9.3 Methods The task class has 16 methods which are closely related to their smx counterparts. Method Definitions: BOOLEAN Start(); BOOLEAN Start( word parm ) BOOLEAN Start( byte Priority ) BOOLEAN Start( const void (*NewTaskMain), byte Priority ); BOOLEAN Stop( word timeout=INF ); void Lock(); BOOLEAN Resume(); void StackCheckOn(); void StackCheckOff(); BOOLEAN Suspend( word timeout=INF ); void Unlock(); BOOLEAN IsLocked(); NOTE: Hook, Lock, StackCheckOn, StackCheckOff, Unlock, Sleep, and SleepStop may be used only for the current task. Attempting to use them for another task results in an OP_NOT_ALLOWED error. 9.3.1 Hook The hook method works just like its smx counterpart. 9.3.2 Start There are three start methods. They all start a task. The first one takes no parameters; it just starts the task. The second one passes a parameter to the task, changes the task's priority, then starts it. The third does all the above, plus giving the task a new main function pointer. This version is similar to the NEWSTART macro in smx. 9.3.3 Stop The stop method works just like its smx counterpart. 9.3.5 Lock The lock method works just like its smx counterpart. 9.3.6 Resume The resume method works just like its smx counterpart. 17 9.3.7 StackCheckOn/StackCheckOff These two methods work like the smx function StackCheck with the parameters ON and OFF, respectively. 9.3.8 Suspend The suspend method works just like its smx counterpart. 9.3.9 Unlock The unlock method works just like its smx counterpart. 9.3.10 Sleep The sleep method works just like its smx counterpart. 9.3.11 SleepStop The sleepstop method works just like its smx counterpart. 9.3.12 IsLocked Works just like in smx. 9.4 Destructor The task class destructor releases the TaskCBP and the task control block back to the system. 10.0 Event Class The event class functions like the smx event table object. It is used to allow task to wait on a specific event. 10.1 Data Members The event class has only one data member which is the pointer to the event table. It is a private data member. ECT_PTR EventTP; 18 10.2 Constructor The event class has only one constructor. It will create the event table with the specified number of slots for tasks. It uses the create_et function. Event( word num ); Event( ECT_PTR p ); 10.3 Methods The event class has four member function. They perform the same functions as their smx counterparts. void ResetFlags( int mask ); void SetFlags( int mask ); int TestFlags( int mask, word timeout=INF ); int TestFlagStop( int mask, word timeout=INF ); 10.3.1 ResetFlags This method functions like its smx counterpart. 10.3.2 SetFlags This method functions like its smx counterpart. 10.3.3 TestFlags This method functions like its smx counterpart. 10.3.3 TestFlagsStop This method functions like its smx counterpart. 10.4 Destructor The event class destructor will send the smx event table control block back to the system. 11.0 Process Class This class is totally defined by the user. It is made up of all the previously defined objects. When the user defines a block of work i.e a process, it will take many smx++ object to preform that function. Since the process class will be designed to 19 perform a specific job there is no one way to build just one type. The process class provides the functions for creating and destroying all smx objects associated with it. This prevents messages and other objects from accumulating in tasks as they are created and deleted. The following is the process base class. It provides a start and shutdown method. Both the methods are pure virtual and are left up to the derived classes to define. class Process { public: BOOLEAN Start()=0; // Start the process BOOLEAN ShutDown()=0; //Stop the process, does not delete }; 11.1 Communication Process The communication process is the communication subsystem taken from the smx User Guide page 5. This example shows how a particular system can be subdivided into subsystems by the use of a process. class Communication : Public Process { // smx++ objects NrmXchg TxXchg; // Transmit message NrmXchg RcvXchg; // Receive Message Bucket TxBkt; // Transmit bucket Bucket RcvBkt; // Receive Bucket Task SendTsk; // Send Task Task RcvTsk; // Receive Task // Constructor Communication( int port, int buf, const cdecl void (*TxMain), byte Txpri, const cdecl void (*RcvMain), byte Rcvpri ): TxXchg(0,0). RcvXchg(0,0), TxBkt(buf), RcvBkt(buf), SendTsk(TxMain, Txpri), RcvTsk( RcvMain, RcvTsk ) ; // Methods Note: We inherit the start and shutdown method BOOLEAN Send( const Message& msg ); BOOLEAN Receive( const Message& msg ); }; 20 11.1.1 Communication smx++ Objects The communication process is made up of six smx++ objects. They consist of the following types: Normal Exchange, Bucket and Task. Two of each object is needed for a full duplex system. 11.1.2 Normal Exchange The normal exchanges are used as the message queue. They act as the message buffers for the process 11.1.3 Buckets The buckets are used to interface a serial device with the message structure. The user will want to derive his own version of bucket to connect to his particular hardware. 11.1.4 Tasks The two task perform the send and receive work for the process. You would want to put any headers or trailers on the messages in these task. 11.2 Constructor There is only one constructor for the communication process. It takes all the parameters that are necessary to create all the objects. The user will have to determine what parameters are necessary for the objects. This will reduce the number of parameters. 11.3 Methods The communication process has for methods. Two which it inherited from the base process class and two that it defines itself. The following is a list of the methods: BOOLEAN Start(); BOOLEAN ShutDown(); BOOLEAN Send( const Message& msg ); BOOLEAN Receive( const Message& msg ); 11.3.1 Start This method is used to start the process. Since they process can be a very complicated class you will want to specify a start up sequence. Start takes no parameters and returns a BOOLEAN indicating that the process was started. 21 11.3.2 ShutDown This method works just the opposite of the of the start method. It is used to shutdown the process in a orderly fashion. It takes no parameters and return a BOOLEAN indicating that the process was shut down correctly. 11.3.3 Send This method is used to send a message to the process. Send will enqueue the message in the transmit exchange. It take a message reference for a parameter. 11.3.4 Receive This method is used to receive a message to the process. Receive will remove the next message in the receive exchange. It take a message reference for a parameter. 12.0 Memory Management With C++, memory management is done through new and delete. New and delete will use the Borland default heap for efficiency. Users can overload new and delete for class specific functions. smx++ supports all the memory management schemes that smx supports, except dynamic allocated regions. 12.1 Memory management schemes smx is rich with management scheme. They include the pool, compiler heap and the smx heap. The compiler heap will be accessed through new and delete. They pool through its class and the smx heap through its "C" functions. 13.0 Error Handling smx++ error handling will be an extension of smx error handling and will use the smx error manager. Since most methods utilize underlying smx functions, many errors will be the same for smx++ as for smx. However, many smx errors cannot occur when using the smx++ API. For example, TaskA.Start cannot return INVALID_TCB. In other cases, errors should be renamed. For example, "INVALID_MCB" is not as meaningful as "NOT_HOLDING" for MsgX.Send(). In this example, by testing MCB_PTR for NULL in the smx++ class code, the send() call can be avoided. Hence, INVALID_MCB will not occur. New error codes will be added to accommodate new errors. 22 13.1 Constructor Error Handling When an object is constructed it will be necessary to indicate if it was successful. With smx++, all constructors will be attempting to get a control block of some kind. If this should fail the instance will still be constructed, but the control block pointer will be set to NULL. This will be an indication to the methods that the smx object could not be created. They will not attempt to perform there desired function and just abort setting an error. In some cases it will be a normal occurrence to not have an smx object ( message class ) so the errors will have to be tailored for the specific case. One finial not, objects can come from three places, global memory, stack, and heap. In the case were there are coming from global and stack memory Borland will respond with an error at compile time if it cannot build the class. In the case of the heap, where the new operator is used to assign a class to a pointer. The new operator will return a NULL if it cannot create the class from the heap. 13.2 Destructor Error Handling The destructor will have to handle the situation where a destructor is called and the object or a subsidiary object is still in use. The system response to this will be to abort and report on OBJECT_IN_USE error. 14.0 smx++ Error List Additions 14.1 NOT_HOLDING A message object does not have a message to send. 14.2 HOLDING A message object cannot receive a message. 14.3 INVALID_PARM The constructor was not able to create the instance of the class. It will signify that a parameter was bad. 23 14.4 OBJECT_IN_USE This error occurs when the destructor is called and the object is still in use. See 13.2 for a detailed explanation. 14.5 WRONG_MCB_TYPE This error occurs when the user try's to use a message that is not from the near heap has a SIOBus buffer. ( See section 6.3.5 Put ) 14.6 OBJECT_NOT_CREATED This error occurs when a class is created and it can not get a control block and one of its methods is used. The method will check the control block pointer for NULL to determine if a control block was obtained from the system. 24