install_tasker (FALSE, 4,
 IFL_DISK|IFL_PRINTER, "FindRoot");

create_task (&tcb3, task3, stack3,
           STACKSIZE, PRI_STD,
           NULL, "TASK3");

Since all task management functions require a TCB pointer, your application should maintain TCB pointers in a common area. Alternately, you can search for the TCB with find_name and the ASCII string assigned to the task. Since find_name simply performs a linear search, the efficiency of your application may suffer. You can disable object naming and thus eliminate its overhead completely by changing TSKCONF.H as follows:

#define TSK_NAMEPAR      FALSE

The CTask scheduling algorithm always picks the highest priority eligible task as the next task to run. CTask uses a priority "aging" mechanism to prevent starvation of low-priority processes. Accordingly, each time a process is not picked as the next task to run, its current priority gets incremented. Thus, even the lowest priority task will eventually rise to the top and get its time-slice. After a task finishes its time-slice, its priority is reset back to the base priority and it is inserted back into the priority queue.

The highest priority task in the system is normally the timer task; its priority defaults to F000h. The install_tasker function assigns the next highest priority to the "main task." This allows the main task to process all initializations before the other tasks start running very far. For successful operation, the main task must eventuallly have its priority reduced or be put in a waiting state. Otherwise, the newly spawned tasks would not get much chance to accomplish any work.

A CTask flag is a boolean semaphore that can be accessed by any task or even an interrupt handler. The create_flag function instantiates the flag and sets it to zero. As with all other CTask objects, flags may be optionally named with an ASCII string. The delete_flag function destroys the flag and kills any threads still waiting for it. The wait_flag_set and wait_flag_clear functions suspend the calling task until the condition is fulfilled or timeout occurs. When the flag changes state, all tasks that were waiting are simultaneously restarted. If you simply want to find out the current state of the flag, you can call the non-blocking check_flag function. Effectively, the Ctask flag acts as a semaphore for a bunch of tasks rather than just a single task.

A Ctask counter resembles the traditional counted semaphore more closely than the flag resource does. Flags may contain only boolean values, but counters can contain any value from 0 to 232 — 1. The create_counter function instantiates the counter and sets it to zero. Similarly, the delete_flag function destroys the flag and kills any threads still waiting for it. The semantics of waiting for a counter are different than waiting for a flag.

The wait_counter_set and wait_counter_clear functions suspend the calling task until the condition is fulfilled or timeout occurs. When waiting for a zero (clear) condition, all tasks will be reactivated upon completion. However, when waiting for a non-zero (set) condition, only the first task will be reactivated. Additionally, the counter is simultaneously decremented as the task is restarted. Normally, the counter changes state only when inc_counter or dec_counter are called. The clear_counter and set_counter functions let your application override the state progression at any time. Last, the check_counter function returns the current state of any counter.

CTask mailboxes, created with the create_mailbox function, can hold an unlimited number of messages. Although a mail message is just an unstructured block of bytes, you must reserve the first four bytes for the CTask kernel. Furthermore, Wagner recommends using a standard size message block to simplify your free block management routines. Mailbox messages are unbuffered but guaranteed to arrive in FIFO order. Accordingly, the receiver should be expected to either free or re-use the incoming message block. Similarly, the sender should refrain from modifying the block after calling send_mail.

The receiver can call wait_mail to wait in a suspended state until mail arrives or a specified timeout occurs. Interrupt handlers are not allowed to use wait_mail. Alternately, c_wait_mail reads mail only if available rather than blocking the task. The check_mail function returns a boolean value corresponding to mail availability. When multiple tasks are waiting for the same mailbox, the task with the highest priority always gets it. Last, delete_mail destroys the mailbox and any remaining tasks waiting for its mail.

CTask pipes, unlike mailboxes, are fully buffered intertask communication constructs. Pipes created with create_pipe hold byte-sized objects while pipes created with create_wpipe hold word-sized objects. The pipe buffer and pipe size (in bytes) are two of the parameters of these functions. Unlike the mailbox, system information is stored in a separate pipe control block data structure rather than inside the actual message buffer.

Reading and writing from pipes is analogous to the fgetc and fputc functions in the C runtime library. A task can call write_pipe without being blocked as long as the pipe is not full. Alternately, the c_write_pipe function puts data in the pipe if it is not currently full. You can find out how much space is left in the pipe by calling pipe_free. Tasks may use read_pipe or c_read_pipe to get data out of the pipe. The former blocks until read or a timeout occurs and the latter reads only if data is curently available. You can invalidate the remaining contents of the pipe with flush_pipe. Last, the delete_pipe function destroys the pipe and any remaining tasks waiting for it.

CTask buffers are actually implemented with pipes and semaphores, thus making them the highest level of intertask communication. Buffers are meant to streamline the handling of variable-length message strings. The documentation does not specify whether or not these are meant to be zero-terminated (ASCIZ) strings. The total size of the string buffer is one of the parameters to create_buffer. Tasks calling write_buffer will be blocked or suffer timeouts if insufficient space remains to fit the entire string. Alternately, the c_write_buffer function will return immediately if unable to write the whole string. Similarly, read_buffer and c_read_buffer allow blocked and non-blocked fetching from the buffer. The reading functions also have maximum size parameters to prevent overrun. You can call check_buffer to find the total amount of bytes remaining in the buffer. Last, the delete_buffer function destroys the buffer and kills any remaining tasks waiting for it.

CTask does not provide support for the extra buffering capabilites of the NS16550AFN UART chips. The 16550 family chips provide 16-byte FIFO transmit and receive buffers as compared to the single-byte buffer of the older 8250 and 16450 chips. Since CTask v2.2 was released before the 16550 came into widespread use, this omission is not surprising.

I traced the 38,400 baud limitation to a static array of baud rates and precomputed baud rate divisors. The baud_rate[] table should be extensible to accommodate 57,600 baud (divisor==2) and 115,200 baud (divisor==1). However, these rates were probably excluded because the code might not be efficient enough to run without data loss on PCs with 8088 CPUs.

Before any serial function can be used, the handler must be installed by calling v24_install. An example invocation of v24_install is:

siop = v24_install(COM1, TRUE, rcvbuf,\\
                sizeof(rcvbuf), xmtbuf, sizeof(xmtbuf));

CTask provides a complete set of port control functions. These functions manually set DTR, RTS, baud rate, parity, word length, and number of stop bits. CTask also lets you set the flow control parameters governing the receive and transmit buffers. Specifically, the v24_protocol function sets XON-XOFF and/or RTS-CTS handshaking as desired. Additionally, it sets the minimum threshold number of characters in the receive buffer before flow-off is asserted and the minimum number of characters before flow-on is reasserted.

Once properly initialized, receiving and transmitting characters is very easy. The v24_send function sends a single character with a timeout parameter. The v24_receive function waits for an incoming character or a timeout, whichever comes first. For polling, v24_check tells whether any characters are in the receive buffer and v24_complete tells whether any characters are in the transmit buffer.

When you are done with an individual serial port, you can deinstall the handler by calling v24_remove. Alternately, you can remove all serial handlers simultaneously by calling v24_remove_all.

The manual is divided into two roughly equal parts of tutorial and reference materials. The tutorial section correctly assumes the reader has no prior experience with writing multi-tasking software. The second half covers the support functions grouped by categories (e.g. task management). The manual finishes with a detailed revision history going back to the first release and an index of all function names. The manual could be improved by the addition of code fragments, sample programs, and more figures. Also, since CTask includes full source-code, the source filename in which each function actually resides should be included as part of its description. For example, I had to resort to grep to find out that read_buffer is implemented in TSKBUF.C. The overall documentation quality is comparable to that supplied with commercial multi-taskers (see bibliography).

Since CTask is freeware, without any remuneration to the author, one might expect a dearth of support. However, Wagner promises to "try his best to eliminate any bugs reported ... and to incorporate suggested enhancements and changes." Although he can be reached directly in Germany, he prefers contact through electronic mail. Specifically, he moderates the ibm.other conference on BYTE magazine's BIX online service. You can leave comments and questions under the topic ctask in that conference. Additionally, Wagner pledges that new versions of CTask will always appear first on BIX. He also includes detailed BIX signup information for first time users. For those inclined to use Internet, he can be reached via a UUCP mailing address as well.

Volkman, Victor R. July 1990. "Multitasking with the DESQview API C Library." The C Users Journal. Vol. 8, No. 7. pp. 99-109.

Volkman, Victor R. December 1990 "DIVVY Multitasking Library." The C Users Journal. Vol. 8, No. 12. p. 100.

Volkman, Victor R. October 1991. "Conquer Multitasking with Conquerrent C." The C Users Journal. Vol. 9, No. 10. pp. 64-70.