Specifiction for Eric v2.0
By Gavin R. Brewer
27/07/01
kThread::kThread( long& hThread );
Description:
Creates a new thread within the current task. The new thread has no processor state, and has a suspend count of 1.
To get a new thread to run, first the constructor is called to get the new thread's identifier, (hThread). Then set_state() is called to set a processor state, and finally resume() is called to get the thread scheduled to execute.
When the thread is created, send rights to its thread kernel port are given to it and returned to the caller in child_thread. The new thread's exception port is set to PORT_NULL.
Arguments:
parent_task The task which is to contain the new thread
child_task The new thread.
Throws:
ERIC_RESOURCE_SHORTAGE Some critical kernel resource is not available
kThread::~kThread();
Description:
~kThread() destroys the current thread.
int kThread::suspend();
int kThread::suspend(long target_thread);
Arguments:
target_thread The thread to be suspended.
Description:
Increments the thread's suspend count and prevents the thread executing any more user level instructions. In this context a user level instruction is either a machine instruction executed in user mode or a system trap instruction including page faults.
Thus if a thread is currently executing within a system trap, the kernel code may continue to execute until it reaches the system return code or it may suspend within the kernel code. In either case, when the thread is resumed, the system trap will return.
This could cause unpredictable results if the user did a suspend and then altered the user state of the thread in order to change its direction upon a resume. The call abort() is provided to allow the user to abort any system call taht is in progress in a predicatable way. Returns:
ERIC_SUCCESS The thread has been suspended.
ERIC_INVALID_ARG target_thread is not a thread.
int kThread::resume();
Description:
Decrements the thread's suspend count. If the count becomes zero the thread is resumed. If it is still positive, the thread is left suspended. The suspend cound may not become negative. Returns:
ERIC_SUCCESS The thread has been resumed
ERIC_FAILURE The suspend count is already zero.
int kThread::abort();
Description:
Aborts the kernel primitives: kMsg::send, kMsg::receive, and kMsg::rpc, and page-faults, making the call return a code indicating that it was interrupted. The call is interrupted whether or not the thread (or task containing it) is currently suspended.
If it is suspended, the thread receives the interrup when it is resumed. This call also aborts any priority depression caused by the DEPRESS option to kThread::switch().
Returns:
ERIC_SUCCESS The thread received an interrupt.
ERIC_INVALID_ARG target_thread is not a thread.
int kThread::get_special_port(int which_port, long& special_port);
int kThread::set_special_port(int which_port, long& special_port);
int kThread::self();
int kThread::reply();
Arguments:
which_port The port that is requested. Is one of:
THREAD_REPLY_PORT,
THREAD_EXCEPTION_PORT
special_port The value of the port that is being requested
or being set..
Description:
Get_special_port() returns send rights to one of a set of special ports for the current thread.
In the case of getting the thread's own thread_reply_port, receive and ownership rights are also given to the thread.
set_special_port() sets one of a set of special ports specified by Thread.
self() returns the port to which kernel calls for the currently executing thread should be directed. Currently, self() returns the 'thread kernel port' which is a port for which the kernel has receive rights and which it uses to identify a thread.
If one thread, the controller, has send access to the kernel port of another thread, the subject thread, then the controller thread can perform kernel operations for the subject thread. Normally only the thread itself and its parent task will have access to the thread kernel port, but any thread may pass rights to its kernel port to any other thread.
reply() returns receive, ownership and send rights to the 'reply port' of the calling thread. The reply port is a port to which the thread has receive rights. It is used to receive any initialization messages and as a reply port for easrly remote procedure calls.
A thread has access to it's task's special ports.
N.B. Using inhertance to implement a Task->Thread superclass relationship may be introduced into our third prototype. For the time being however, we will treat them as separate classes.
int kThread::info(long& target_thread,
int flavor, Array<int>* info,
int info_Cnt);
int kThread::info(int flavor, Array<int>* info, int info_Cnt);
Arguments:
target_thread The thread to be affected
flavor The type of statistics that are wanted. Currently only THREAD_BASIC_INFO is implemented thread_info Statistics about the thread specified by target_thread.
info_Cnt Size of the info structure. Currently only THREAD_BASIC_INFO_COUNT is implemented.
Description:
Returns the selected information array for a thread, as specified by flavor, Array<int> is essentially an array of integers that are supplied by the caller and returned filled with specified information.
info_Cnt is supplied as the maximum number of integers in thread_info. On return, it contains the actual number of integers in thread_info.
Currently thre is only one flavor of information which is defined by THREAD_BASIC_INFO. Its size is defined by THREAD_BASIC_INFO_COUNT.
Returns:
ERIC_SUCCESS The call suceeded
ERIC_INVALID_ARG target_thread is not a thread or flavor is not recognised.
EIG_ARRAY_TOO_LARGE
Returned info array is too large for thread_info. This array is filled as much as possible. info_Cnt is set to the number of elements that would have been returned if there were enough room.
int kThread::get_state( long& target_thread,
int flavor,
Array <int> old_state,
old_stateCnt);
int kThread::set_state( long& target_thread,
int flavor,
Array <int> new_state,
new_stateCnt);
Arguments:
flavor The type of state that is to be manipulated. Currently must be one of the following values: VAX_THREAD_STATE, ROMP_THREAD_STATE, SUN_THREAD_STATE_REGS SUN_THREAD_STATE_FPA
new_state an array of state information old_state an array of state information new_stateCnt the size of the state information array. Currently must be one of the following values:
VAX_THREAD_STATE_COUNT,
ROMP_THREAD_STATE_COUNT
SUN_THREAD_STATE_COUNT,
SUN_THREAD_STATE_FPA_COUNT
old_stateCnt same as new_stateCnt
Description:
get_state() returns the state component (e.g. the machine registers) of target_thread as specified by flavor. The old_state is an array of integers that is provided bu the caller and returned filled with the specified information. old_stateCnt is input set to the maximum number of integers in old_state, and returned equal to the actual number of integers in old_state.
set_state() sets the state component (e.g. the machine registers) of target_thread as specified by flavor. Thew new_state is an array of integers. new_stateCnt is the number of elements in new_state. The entire set of register is reset. This will do unpredicatable things if target_thread is not suspended.
target_thread may not be the current thread for either of these calls.
Returns:
ERIC_SUCCESS The state has been set or returned
ERIC_INVALID_ARG target_thread is not a thread or is the current thread, or the flavor is not recognised for this machine.
EIG_ARRAY_TOO_LARGE Returned state is too large for the new_state array. new_state is filled in as much as possible and new_stateCnt is set to the number of elements that would be returned if there were enough room..