|
ZestCode
|
|
|
ZestCode
|
|
Files | |
| file | rtos.h |
Macros | |
| #define | CURRENT_TASK ((task_t)NULL) |
Functions | |
| uint32_t | millis (void) |
| uint64_t | micros (void) |
| task_t | task_create (task_fn_t function, void *const parameters, uint32_t prio, const uint16_t stack_depth, const char *const name) |
| void | task_delete (task_t task) |
| void | task_delay (const uint32_t milliseconds) |
| void | delay (const uint32_t milliseconds) |
| void | task_delay_until (uint32_t *const prev_time, const uint32_t delta) |
| uint32_t | task_get_priority (task_t task) |
| void | task_set_priority (task_t task, uint32_t prio) |
| task_state_e_t | task_get_state (task_t task) |
| void | task_suspend (task_t task) |
| void | task_resume (task_t task) |
| uint32_t | task_get_count (void) |
| char * | task_get_name (task_t task) |
| task_t | task_get_by_name (const char *name) |
| task_t | task_get_current () |
| uint32_t | task_notify (task_t task) |
| void | task_join (task_t task) |
| uint32_t | task_notify_ext (task_t task, uint32_t value, notify_action_e_t action, uint32_t *prev_value) |
| uint32_t | task_notify_take (bool clear_on_exit, uint32_t timeout) |
| bool | task_notify_clear (task_t task) |
| mutex_t | mutex_create (void) |
| bool | mutex_take (mutex_t mutex, uint32_t timeout) |
| bool | mutex_give (mutex_t mutex) |
| mutex_t | mutex_recursive_create (void) |
| bool | mutex_recursive_take (mutex_t mutex, uint32_t timeout) |
| bool | mutex_recursive_give (mutex_t mutex) |
| void | mutex_delete (mutex_t mutex) |
Enumerations | |
| enum | task_state_e_t { E_TASK_STATE_RUNNING = 0 , E_TASK_STATE_READY , E_TASK_STATE_BLOCKED , E_TASK_STATE_SUSPENDED , E_TASK_STATE_DELETED , E_TASK_STATE_INVALID } |
| enum | notify_action_e_t { E_NOTIFY_ACTION_NONE , E_NOTIFY_ACTION_BITS , E_NOTIFY_ACTION_INCR , E_NOTIFY_ACTION_OWRITE , E_NOTIFY_ACTION_NO_OWRITE } |
Typedefs | |
| typedef void * | task_t |
| typedef void(* | task_fn_t) (void *) |
| typedef void * | mutex_t |
Macros | |
| #define | TASK_PRIORITY_MAX 16 |
| #define | TASK_PRIORITY_MIN 1 |
| #define | TASK_PRIORITY_DEFAULT 8 |
| #define | TASK_STACK_DEPTH_DEFAULT 0x2000 |
| #define | TASK_STACK_DEPTH_MIN 0x200 |
| #define | TASK_NAME_MAX_LEN 32 |
| #define | TIMEOUT_MAX ((uint32_t)0xffffffffUL) |
| #define CURRENT_TASK ((task_t)NULL) |
The task handle of the currently running task.
| #define TASK_NAME_MAX_LEN 32 |
The maximum number of characters allowed in a task's name.
| #define TASK_PRIORITY_DEFAULT 8 |
The default task priority, which should be used for most tasks unless you have a specific need for a higher or lower priority task.
The default tasks, such as autonomous(), are run with this priority
| #define TASK_PRIORITY_MAX 16 |
The highest priority that can be assigned to a task.
A task with this priority will always run if it is available to. Beware of deadlocks when using this priority.
| #define TASK_PRIORITY_MIN 1 |
The lowest priority that can be assigned to a task.
This can cause severe performance problems and is generally not recommended that users use this priority.
| #define TASK_STACK_DEPTH_DEFAULT 0x2000 |
The recommended stack size for a new task.
This stack size is used for the default tasks such as autonomous(). This size is 8,192 words, or 32,768 bytes. This should be enough for the majority of tasks
| #define TASK_STACK_DEPTH_MIN 0x200 |
The minimal stack size for a task.
This equates to 512 words, or 2,048 bytes.
| #define TIMEOUT_MAX ((uint32_t)0xffffffffUL) |
The maximum timeout value that can be given to, for instance, a mutex grab.
| typedef void* mutex_t |
A mutex.
A mutex is a synchronization object that can be used to protect a shared resource from being accessed by multiple tasks at the same time. A mutex can be claimed by a task, which will prevent other tasks from claiming it until that task releases it.
| typedef void(* task_fn_t) (void *) |
A pointer to a task's function.
Such a function is called when a task starts, and exiting said function will terminate the task.
| typedef void* task_t |
An opaque type that pontis to a task handle. This is used for referencing a task.
| enum notify_action_e_t |
brief The action to take when a task is notified.
| enum task_state_e_t |
The state of a task.
| void delay | ( | const uint32_t | milliseconds | ) |
Delays the current task for a given number of milliseconds.
This is not the best method to have a task execute code at predefined intervals, as the delay time is measured from when the delay is requested. To delay cyclically, use task_delay_until().
| milliseconds | The number of milliseconds to wait (1000 milliseconds per second) |
Example
| uint64_t micros | ( | void | ) |
Gets the number of microseconds since PROS initialized,
Example
| uint32_t millis | ( | void | ) |
Gets the number of milliseconds since PROS initialized.
Example
| mutex_t mutex_create | ( | void | ) |
Creates a mutex.
See https://pros.cs.purdue.edu/v5/tutorials/topical/multitasking.html#mutexes for details.
Example
| void mutex_delete | ( | mutex_t | mutex | ) |
Deletes a mutex or recursive mutex
| mutex | Mutex to unlock. |
Example
| bool mutex_give | ( | mutex_t | mutex | ) |
Unlocks a mutex.
See https://pros.cs.purdue.edu/v5/tutorials/topical/multitasking.html#mutexes for details.
| mutex | Mutex to unlock. |
Example
| mutex_t mutex_recursive_create | ( | void | ) |
Creates a recursive mutex which can be locked recursively by the owner.
Example:
| bool mutex_recursive_give | ( | mutex_t | mutex | ) |
Gives a recursive mutex.
| mutex | A mutex handle created by mutex_recursive_create |
Example:
| bool mutex_recursive_take | ( | mutex_t | mutex, |
| uint32_t | timeout ) |
Takes a recursive mutex.
| mutex | A mutex handle created by mutex_recursive_create |
| wait_time | Amount of time to wait before timing out |
Example:
| bool mutex_take | ( | mutex_t | mutex, |
| uint32_t | timeout ) |
Takes and locks a mutex, waiting for up to a certain number of milliseconds before timing out.
See https://pros.cs.purdue.edu/v5/tutorials/topical/multitasking.html#mutexes for details.
| mutex | Mutex to attempt to lock. |
| timeout | Time to wait before the mutex becomes available. A timeout of 0 can be used to poll the mutex. TIMEOUT_MAX can be used to block indefinitely. |
Example
| task_t task_create | ( | task_fn_t | function, |
| void *const | parameters, | ||
| uint32_t | prio, | ||
| const uint16_t | stack_depth, | ||
| const char *const | name ) |
Creates a new task and add it to the list of tasks that are ready to run.
This function uses the following values of errno when an error state is reached: ENOMEM - The stack cannot be used as the TCB was not created.
| function | Pointer to the task entry function |
| parameters | Pointer to memory that will be used as a parameter for the task being created. This memory should not typically come from stack, but rather from dynamically (i.e., malloc'd) or statically allocated memory. |
| prio | The priority at which the task should run. TASK_PRIO_DEFAULT plus/minus 1 or 2 is typically used. |
| stack_depth | The number of words (i.e. 4 * stack_depth) available on the task's stack. TASK_STACK_DEPTH_DEFAULT is typically sufficienct. |
| name | A descriptive name for the task. This is mainly used to facilitate debugging. The name may be up to 32 characters long. |
Example
| void task_delay | ( | const uint32_t | milliseconds | ) |
Delays the current task for a given number of milliseconds.
This is not the best method to have a task execute code at predefined intervals, as the delay time is measured from when the delay is requested. To delay cyclically, use task_delay_until().
| milliseconds | The number of milliseconds to wait (1000 milliseconds per second) |
Example
| void task_delay_until | ( | uint32_t *const | prev_time, |
| const uint32_t | delta ) |
Delays the current task until a specified time. This function can be used by periodic tasks to ensure a constant execution frequency.
The task will be woken up at the time *prev_time + delta, and *prev_time will be updated to reflect the time at which the task will unblock.
| prev_time | A pointer to the location storing the setpoint time. This should typically be initialized to the return value of millis(). |
| delta | The number of milliseconds to wait (1000 milliseconds per second) |
Example
| void task_delete | ( | task_t | task | ) |
Removes a task from the RTOS real time kernel's management. The task being deleted will be removed from all ready, blocked, suspended and event lists.
Memory dynamically allocated by the task is not automatically freed, and should be freed before the task is deleted.
| task | The handle of the task to be deleted. Passing NULL will cause the calling task to be deleted. |
Example
| task_t task_get_by_name | ( | const char * | name | ) |
Gets a task handle from the specified name
The operation takes a relatively long time and should be used sparingly.
| name | The name to query |
Example
| uint32_t task_get_count | ( | void | ) |
Gets the number of tasks the kernel is currently managing, including all ready, blocked, or suspended tasks. A task that has been deleted, but not yet reaped by the idle task will also be included in the count. Tasks recently created may take one context switch to be counted.
Example
| task_t task_get_current | ( | ) |
Get the currently running task handle. This could be useful if a task wants to tell another task about itself.
Example
| char * task_get_name | ( | task_t | task | ) |
Gets the name of the specified task.
| task | The task to check |
Example
| uint32_t task_get_priority | ( | task_t | task | ) |
Gets the priority of the specified task.
| task | The task to check |
Example
| task_state_e_t task_get_state | ( | task_t | task | ) |
Gets the state of the specified task.
| task | The task to check |
Example
| void task_join | ( | task_t | task | ) |
Utilizes task notifications to wait until specified task is complete and deleted, then continues to execute the program. Analogous to std::thread::join in C++.
| task | The handle of the task to wait on. |
Example
| uint32_t task_notify | ( | task_t | task | ) |
Sends a simple notification to task and increments the notification counter.
| task | The task to notify |
Example
| bool task_notify_clear | ( | task_t | task | ) |
Clears the notification for a task.
See https://pros.cs.purdue.edu/v5/tutorials/topical/notifications.html for details.
| task | The task to clear |
Example
| uint32_t task_notify_ext | ( | task_t | task, |
| uint32_t | value, | ||
| notify_action_e_t | action, | ||
| uint32_t * | prev_value ) |
Sends a notification to a task, optionally performing some action. Will also retrieve the value of the notification in the target task before modifying the notification value.
| task | The task to notify |
| value | The value used in performing the action |
| action | An action to optionally perform on the receiving task's notification value |
| prev_value | A pointer to store the previous value of the target task's notification, may be NULL |
Example
| uint32_t task_notify_take | ( | bool | clear_on_exit, |
| uint32_t | timeout ) |
Waits for a notification to be nonzero.
See https://pros.cs.purdue.edu/v5/tutorials/topical/notifications.html for details.
| clear_on_exit | If true (1), then the notification value is cleared. If false (0), then the notification value is decremented. |
| timeout | Specifies the amount of time to be spent waiting for a notification to occur. |
Example
| void task_resume | ( | task_t | task | ) |
Resumes the specified task, making it eligible to be scheduled.
| task | The task to resume |
Example
| void task_set_priority | ( | task_t | task, |
| uint32_t | prio ) |
Sets the priority of the specified task.
If the specified task's state is available to be scheduled (e.g. not blocked) and new priority is higher than the currently running task, a context switch may occur.
| task | The task to set |
| prio | The new priority of the task |
Example
| void task_suspend | ( | task_t | task | ) |
Suspends the specified task, making it ineligible to be scheduled.
| task | The task to suspend |
Example
1.13.2