KOS contains a fully functional thread system, including priority based scheduling, thread sync primitives with their own queues, zero-CPU-usage sleeping, and the choice between cooperative and pre-emptive thread models.
In the cooperative thread model, a thread will only ever be interrupted if it manually places itself on a wait queue. This can be accomplished by calling the thd_sleep function or waiting on an unavailable thread sync primitive. Use of cooperative threading mode with multiple threads has not really been tested very well, so use it at your own risk. We currently recommend sticking with a single thread if you want to use cooperative mode (this is what it was mainly designed for).
In pre-emptive mode, a timer interrupt is called HZ times per second (a constant in arch.h) to re-schedule. The current thread is placed back on the ready queue and another thread is pulled from it. This may be the same thread if no other threads are running. The effect is what you usually see in modern operating systems when running more than one program at once - all of the programs seem to be running simultaneously. The very big difference between those schedulers and the KOS pre-emptive scheduler is that KOS' scheduler does exactly what you tell it to do. There are no temporary priority boosts or decay, or anything of the like. This means that, like most real-time embedded kernels, if you place a thread at a high priority, no other thread will execute until it is sleeping, has had its priority lowered, or quits. I highlight the previous statement because thread priorities may be very useful for your application, but you must be careful not to cause a situation where your high-priority thread is always the one running. You also have to watch for ``priority inversion'', but discussion of these topics is beyond the scope of this document - go get a CS operating systems textbook. =)
Pre-emptive thread mode is the default (for INIT_DEFAULTS). You can cancel this out by using (INIT_DEFAULTS & ~INIT_THD_PREEMPT) in your KOS_INIT_FLAGS line, or by creating your own bitmask manually and leaving that part out.
On to the function reference...
Creates a new thread and returns the kthread_t structure representing it. The thread will begin at routine, and its single and only parameter will be param. In case of failure, NULL will be returned.
Destroys a previously created thread. This is not recommended. Instead, if at all possible, a thread should quit on its own in a graceful manner. However, if you must kill a thread which hasn't died, then you can use this function. Any resources the thread had allocated or locked (such as memory, thread sync primitives, etc) will not be freed.
Gracefully exit the current thread. This function will never return.
Manually re-schedule. This function is to be called only inside an interrupt/syscall context. It assumes that interrupts are disabled and that we have entered the routine by saving the previous context into the appropriate kthread_t.
Same basic thing as thd_schedule, but you may specify a thread to be manually scheduled next. This can be useful if, for example, a device driver needs to pass control back to some code which was placed on a wait queue as quickly as possible.
The caller voluntarily gives up the rest of its timeslice. Any remaining timeslice will be given to the next scheduled thread. Note that the timeslice does not start over when this happens, so used incorrectly it could theoretically cause starvation issues.
The caller will sleep the requested number of milliseconds. This function will return at a time equal to or greater than the requested delay. This is not guaranteed to be precise, and will certainly not be more precise than HZ allows. While the caller is sleeping, zero CPU time is spent (it is not scheduled at all).
Sets the priority of the given thread. The default priority is PRIO_DEFAULT and the maximum priority is PRIO_MAX. A larger value means lower priority.
Retrive the kthread_t for the caller.
Retrieve the ``thread label'' for the given thread. This is an arbitrary free-form string which identifies the thread for debugging purposes.
Sets the ``thread label'' for the given thread.
Retrieve the current working directory for the given thread. This is used by the VFS for relative paths.
Sets the current working directory for the given thread.