#include <oskit/threads/pthread.h>
#include <oskit/threads/cpuinherit.h>int pthread_sched_donate_wait_recv(pthread_t tid, sched_wakecond_t wakecond, schedmsg_t *msg, oskit_s32_t timeout);
Donate CPU time to a target thread whose pthread identifier is tid. The donation will terminate when the thread gives up the CPU, or when the timeout value is reached. In this way, a scheduler can implement preemptive scheduling by allowing each thread to run for a maximum time value, at which time control returns to the dontating scheduler.The wakecond flag specifies under which circumstances control should be returned to the scheduler when the target thread blocks. There are currently just two values allowed:
- WAKEUP_ON_BLOCK
- Control returns to the scheduler whenever the target thread blocks or otherwise gives up the CPU. This allows the scheduler to make a new scheduling decision.
- WAKEUP_ON_SWITCH
- Control returns to the scheduler's scheduler whenever the target thread blocks or otherwise gives up the CPU. This is typically used when a scheduler has just one thread to schedule, and is not interested in when the target thread blocks or unblocks, but only when some other thread wakes up, requiring an actual scheduling decision to be made.
The return value indicates how the donation was terminated, and is one of the following constants. Its is up to the scheduler to determine the course of action. For example, a donation that returns a SCHEDULE_YIELDED would typically result in the target thread being placed back on the scheduler's run queue so that it will be run at some later point.
- SCHEDULE_NOTREADY
- The target thread is not ready to receive the donation, perhaps because the target thread is blocked.
- SCHEDULE_BLOCKED
- The target thread ran and then blocked for some reason. The thread should not be run until the scheduler receives an MSG_SCHED_UNBLOCK message for the target thread.
- SCHEDULE_YIELDED
- The target thread ran and then voluntarily gave up the CPU. The thread will typically be placed back on the run queue for that scheduler.
- SCHEDULE_PREEMPTED
- The target thread ran and was then preempted by the threads system. The thread will typically be placed back on the run queue for that scheduler.
- SCHEDULE_TIMEDOUT
- The target thread ran until the timeout expired, and was then preempted so that the scheduler may pick another thread to run. The thread will typically be placed back on the run queue for that scheduler.
- SCHEDULE_MSGRECV
- This constant is bitwise or'ed into the result value whenever a thread donation terminates and a scheduling message was returned in the message block pointed to by msg. The scheduler will need to take appropriate action based on the both the return value of the donation, and the contents of the message.
Upon return from the donation, it is possible that a scheduling message will also be ready. Rather than have the scheduler invoke a separate message operation to retrieve the message, the message reception operation is combined with the donation. This is indicated in the return value when the SCHEDULE_MSGRECV bit is set. The format of the message is as follows:
typedef struct schedmsg { schedmsg_types_t type; pthread_t tid; oskit_u32_t opaque; oskit_u32_t opaque2; } schedmsg_t;The message refers to the thread identifed by tid, while opaque and opaque2 are message specific values. Only some message types have associated message values (described below). The message types are as follows:
- MSG_SCHED_NEWTHREAD
- A new thread was created for the current scheduler. The scheduler for a thread is specified using the thread attributes and the textttpthread_attr_setscheduler routine. Once the thread is created and ready to be scheduled, a message is sent to the specified scheduler so that it may set up the necessary data structures, and add the new thread to its run queue. The thread id of the new thread is given by the tid field of the message. Depending on the scheduler, the opaque and opaque2 fields may also be valid.
- MSG_SCHED_UNBLOCK
- The thread specified by the tid field of the message has been unblocked. The scheduler will typically add the thread to its internal run queue so that it will be run again.
- MSG_SCHED_SETSTATE
- Alter the scheduling parameters for the thread specified by the tid field. This message is sent as a result of the application calling pthread_sched_setstate. The opaque and opaque2 fields are obviously specific to the scheduler.
- MSG_SCHED_EXITED
- The thread specified by the tid field of the message has called pthread_exit. The scheduler will typically remove the thread from its internal data structures and free any associated resources.
- tid
- The pthread_t of the thread to donate to.
- wakecond
- The wakeup condition.
- msg
- A message buffer in which to place a message if one is available when the donation ends.
- timeout
- A timeout value, in milliseconds. The donation will be terminated after the time has elapsed.
The return values are described above.
pthread_sched_setstate, pthread_attr_setscheduler