void fluke_thread_set_state(fluke_thread_t *thread, fluke_thread_state *state, fluke_ref_t *task_ref, fluke_ref_t *scheduler_ref, fluke_ref_t *waiting_for_ref, fluke_ref_t *client_ref, fluke_ref_t *server_ref);
This operation can be used to set some or all of the application-visible state of a thread. The caller must ensure that the target thread is not currently running; otherwise the results are undefined (fluke_thread_get_state can be used to ensure the thread is stopped).All of the simple state in the thread, such as the CPU register contents, is loaded from the provided state structure. All references contained in the thread must be set individually from reference objects at the specified addresses. Any of the parameters except thread may be null, in which case the corresponding piece of thread state is not changed.
See fluke_thread_get_state for information on the format of the fluke_thread_state structure.
- thread
- The thread whose state is to be modified. The thread must not be running.
- state
- If non-null, a pointer to a structure containing the simple (non-reference) state of the thread.
- task_ref
- If non-null, must point to an existing reference object which is to be inserted as the thread's task reference. The reference object itself must be either null (invalid) or point to a task object. If a null reference is provided, the thread will not be able to run until a valid reference to a task is inserted again. If the task_ref parameter itself is a null pointer (as opposed to a pointer to a null reference), then the thread's existing task reference is left unchanged.
- scheduler_ref
- If non-null, indicates the reference object to be inserted as the thread's scheduler port reference. The reference must either be null or must point to a port object. If scheduler_ref is a null pointer, then the thread's scheduler reference is unchanged.
- waiting_for_ref
- If this pointer is non-null, a reference to the object the thread is to wait for; See fluke_thread_get_state for details. If the pointer is null, the thread remains waiting on the same object it was already waiting for. Note that this reference is not part of the ``critical'' state of a thread: it can be regenerated at any time based on the thread's current CPU state. If a null reference is inserted into this slot, then the thread will immediately wake up immediately after the fluke_thread_set_state operation completes (assuming the thread has a valid task reference), contacting its scheduler if necessary to obtain CPU time. Even if a non-null reference is inserted here, a Fluke implementation may choose always to ignore it, treating it as if a null reference was provided and waking up the thread immediately.
- client_ref
- If non-null, indicates the reference to be inserted as the thread's client reference. The reference must either be null or must point to a thread object. If client_ref is a null pointer, then the thread's client reference is unchanged.
- server_ref
- If non-null, indicates the reference to be inserted as the thread's server reference. The reference must either be null or must point to a thread object. If server_ref is a null pointer, then the thread's server reference is unchanged.
If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes. All of these have an implicit FLUKE_INSANITY_ prefix.
- NO_OBJECT
- thread does not point to an active object.
- NOT_THREAD
- The object pointed to by thread is not a thread object.
- NOT_REF
- One or more of the provided (non-null) reference parameters is not a valid reference object.
- NOT_TASK_REF
- task_ref is a valid reference object but not a task reference object.
- NOT_PORT_REF
- scheduler_ref is a valid reference object but not a port reference object.
- NOT_THREAD_REF
- One or both of client_ref or server_ref is a valid reference object but not a thread reference object.
- RACE_CONDITION
- An illegal race condition with another thread was detected on one of the objects specified as parameters to this call.
- CURRENT_THREAD
- A thread attempted to set its own state.
- INVALID_OBJECT
- The state of the thread object or one of the reference objects has become invalid or
the provided thread state contains invalid information.
fluke_thread_get_state