RTOS Facilities C API module

uint32_t millis(void)

#include <pros/rtos.h>

Gets the number of milliseconds since PROS initialized.

Example

void opcontrol() {
  uint32_t now = millis();
  while (true) {
    // Do opcontrol things
    task_delay_until(&now, 2);
  }
}

uint64_t micros(void)

#include <pros/rtos.h>

Gets the number of microseconds since PROS initialized,.

Example

void opcontrol() {
  uint64_t now = micros();
  while (true) {
    // Do opcontrol things
    task_delay_until(&now, 2000);
  }
}

task_t task_create(task_fn_t function, void*const parameters, uint32_t prio, const uint16_t stack_depth, const char*const name)

#include <pros/rtos.h>

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.

Example

void my_task_fn(void* param) {
  printf("Hello %s\n", (char*)param);
  // ...
}

void initialize() {
  task_t my_task = task_create(my_task_fn, (void*)"PROS", TASK_PRIORITY_DEFAULT,
                              TASK_STACK_DEPTH_DEFAULT, "My Task");
}

void task_delete(task_t task)

#include <pros/rtos.h>

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.

Example

void my_task_fn(void* param) {
  printf("Hello %s\n", (char*)param);
  // ...
}

void initialize() {
  task_t my_task = task_create(my_task_fn, (void*)"PROS", TASK_PRIORITY_DEFAULT,
                           TASK_STACK_DEPTH_DEFAULT, "My Task");
  // Do other things
  task_delete(my_task);
}

void task_delay(const uint32_t milliseconds)

#include <pros/rtos.h>

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().

Example

void opcontrol() {
  while (true) {
    // Do opcontrol things
    task_delay(2);
  }
}

void delay(const uint32_t milliseconds)

#include <pros/rtos.h>

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().

Example

void opcontrol() {
while (true) {
  // Do opcontrol things
  delay(2);
  }
}

void task_delay_until(uint32_t*const prev_time, const uint32_t delta)

#include <pros/rtos.h>

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.

Example

void opcontrol() {
  uint32_t now = millis();
  while (true) {
    // Do opcontrol things
    task_delay_until(&now, 2);
  }
}

uint32_t task_get_priority(task_t task)

#include <pros/rtos.h>

Gets the priority of the specified task.

Example

void my_task_fn(void* param) {
  printf("Hello %s\n", (char*)param);
  // ...
}

void initialize() {
  task_t my_task = task_create(my_task_fn, (void*)"PROS", TASK_PRIORITY_DEFAULT,
                           TASK_STACK_DEPTH_DEFAULT, "My Task");
  printf("Task Priority: %d\n", task_get_priority(my_task));
}

void task_set_priority(task_t task, uint32_t prio)

#include <pros/rtos.h>

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.

Example

void my_task_fn(void* ign) {
  // Do things
}

void opcontrol() {
  task_t my_task = task_create(my_task_fn, NULL, TASK_PRIORITY_DEFAULT,
                            TASK_STACK_DEPTH_DEFAULT, "Example Task");
  task_set_priority(my_task, TASK_PRIORITY_DEFAULT + 1);
}

task_state_e_t task_get_state(task_t task)

#include <pros/rtos.h>

Gets the state of the specified task.

Example

void my_task_fn(void* param) {
  printf("Hello %s\n", (char*)param);
  // ...
}

void initialize() {
  task_t my_task = task_create(my_task_fn, (void*)"PROS", TASK_PRIORITY_DEFAULT,
                           TASK_STACK_DEPTH_DEFAULT, "My Task");
  printf("Task's State: %d\n", task_get_state(my_task));
}

void task_suspend(task_t task)

#include <pros/rtos.h>

Suspends the specified task, making it ineligible to be scheduled.

Example

mutex_t counter_mutex;
int counter = 0;

void my_task_fn(void* param) {
  while(true) {
    mutex_take(counter_mutex, TIMEOUT_MAX);// Mutexes are used for protecting shared resources
    counter++;
    mutex_give(counter_mutex);
    pros::delay(10);
  }
}

void opcontrol() {
  task_t task = task_create(my_task_fn, NULL, TASK_PRIORITY_DEFAULT,;

  while(true) {
       mutex_take(counter_mutex, TIMEOUT_MAX);
    if(counter > 100) {
      task_suspepend(task);
       }
    mutex_give(counter_mutex);
    pros::delay(10);
  }
}

void task_resume(task_t task)

#include <pros/rtos.h>

Resumes the specified task, making it eligible to be scheduled.

Example

void my_task_fn(void* param) {
  while(true) {
    // Do stuff
    delay(10);
  }
}

task_t task;

void initialize() {
  task = task_create(my_task_fn, NULL, TASK_PRIORITY_DEFAULT,
                    TASK_STACK_DEPTH_DEFAULT, "My Task");
}

void autonomous() {
  task_resume(task);

  // Run autonomous , then suspend the task so it doesn't interfere run
  
  // outside of autonomous or opcontrol
  task_suspend(task);
}

void opcontrol() {
  task_resume(task);
  // Opctonrol code here
  task_suspend(task);
}

uint32_t task_get_count(void)

#include <pros/rtos.h>

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

void my_task_fn(void* param) {
  printf("Hello %s\n", (char*)param);
  // ...
}

void initialize() {
  task_t my_task = task_create(my_task_fn, (void*)"PROS", TASK_PRIORITY_DEFAULT,
                           TASK_STACK_DEPTH_DEFAULT, "My Task");
  printf("Number of Running Tasks: %d\n", task_get_count());
}

char* task_get_name(task_t task)

#include <pros/rtos.h>

Gets the name of the specified task.

Example

void my_task_fn(void* param) {
  printf("Hello %s\n", (char*)param);
  // ...
}

void initialize() {
  task_t my_task = task_create(my_task_fn, (void*)"PROS", TASK_PRIORITY_DEFAULT,
                           TASK_STACK_DEPTH_DEFAULT, "My Task");
  printf("Task Name: %d\n", task_get_name(my_task));
}

task_t task_get_by_name(const char* name)

#include <pros/rtos.h>

Gets a task handle from the specified name.

The operation takes a relatively long time and should be used sparingly.

Example

void my_task_fn(void* param) {
  printf("Hello %s\n", (char*)param);
  // ...
}

void initialize() {
  task_t my_task = task_create(my_task_fn, (void*)"PROS", TASK_PRIORITY_DEFAULT,
                           TASK_STACK_DEPTH_DEFAULT, "My Task");
  // Do other things
  task_delete(task_get_by_name("My Task"));
}

task_t task_get_current()

#include <pros/rtos.h>

Get the currently running task handle.

This could be useful if a task wants to tell another task about itself.

Example

void my_task_fn(void* param) {
  task_t this_task = task_get_current();
  if (task_get_state(this_take) == E_TASK_STATE_RUNNING) {
    printf("This task is currently running\n");
  }
// ...
}

void initialize() {
  task_t my_task = task_create(my_task_fn, (void*)"PROS", TASK_PRIORITY_DEFAULT,
                           TASK_STACK_DEPTH_DEFAULT, "My Task");
}

uint32_t task_notify(task_t task)

#include <pros/rtos.h>

Sends a simple notification to task and increments the notification counter.

Example

void my_task_fn(void* ign) {
  while(task_notify_take(true) == 0) {
    // Code while waiting
  }
  puts("I was unblocked!");
}

void opcontrol() {
  task_t my_task = task_create(my_task_fn, NULL, TASK_PRIORITY_DEFAULT,
                            TASK_STACK_DEPTH_DEFAULT, "Notify me! Task");
  while(true) {
    if(controller_get_digital(CONTROLLER_MASTER, DIGITAL_L1)) {
      task_notify(my_task);
    }
  }
}

void task_join(task_t task)

#include <pros/rtos.h>

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++.

Example

void my_task_fn(void* ign) {
  lcd_print(1, "%s running", task_get_name(NULL));
  task_delay(1000);
  lcd_print(2, "End of %s", task_get_name(NULL));
}

void opcontrol() {
  task_t my_task = task_create(my_task_fn, NULL, TASK_PRIORITY_DEFAULT,
                            TASK_STACK_DEPTH_DEFAULT, "Example Task");
  lcd_set_text(0, "Running task.");
  task_join(my_task);
  lcd_set_text(3, "Task completed.");
}

uint32_t task_notify_ext(task_t task, uint32_t value, notify_action_e_t action, uint32_t* prev_value)

#include <pros/rtos.h>

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.

Example

void my_task_fn(void* param) {
  while(true) {
    // Wait until we have been notified 20 times before running the code
    if(task_notify_take(false, TIMEOUT_MAX) == 20) {
      // ... Code to do stuff here ...

      // Reset the notification counter
      task_notify_take(true, TIMEOUT_MAX);
    }
    delay(10);
     }
}

void opcontrol() {
     task_t task = task_create(my_task_fn, NULL, TASK_PRIORITY_DEFAULT,
                           TASK_STACK_DEPTH_DEFAULT, "My Task");
  
  int count = 0;
  
  while(true) {
    if(controller_get_digital(CONTROLLER_MASTER, DIGITAL_L1)) {
      task_notify_ext(task, 1, NOTIFY_ACTION_INCREMENT, &count);
    }
    
    delay(20);
  }
}

uint32_t task_notify_take(bool clear_on_exit, uint32_t timeout)

#include <pros/rtos.h>

Waits for a notification to be nonzero.

See https://pros.cs.purdue.edu/v5/tutorials/topical/notifications.html for details.

Example

void my_task_fn(void* ign) {
  task_t current_task = task_get_current();
  while(task_notify_take(current_task, true, TIMEOUT_MAX)) {
    puts("I was unblocked!");
  }
}

void opcontrol() {
  task_t my_task = task_create(my_task_fn, NULL, TASK_PRIORITY_DEFAULT,
                            TASK_STACK_DEPTH_DEFAULT, "Notify me! Task");
  while(true) {
    if(controller_get_digital(CONTROLLER_MASTER, DIGITAL_L1)) {
      task_notify(my_task);
    }
  }
}

bool task_notify_clear(task_t task)

#include <pros/rtos.h>

Clears the notification for a task.

See https://pros.cs.purdue.edu/v5/tutorials/topical/notifications.html for details.

Example

void my_task_fn(void* param) {
  task_t task = task_get_current();
  while(true) {
    printf("Waiting for notification...\n");
       printf("Got a notification: %d\n", task_notify_take(task, false, TIMEOUT_MAX));

       task_notify_clear(task);
    delay(10):
  }
}

void opcontrol() {
 task_t task = task_create(my_task_fn, NULL, TASK_PRIORITY_DEFAULT,
                           TASK_STACK_DEPTH_DEFAULT, "My Task");

  while(true) {
    if(controller_get_digital(CONTROLLER_MASTER, DIGITAL_L1)) {
      task_notify(task);
    }
    delay(10);
  }
}

mutex_t mutex_create(void)

#include <pros/rtos.h>

Creates a mutex.

See https://pros.cs.purdue.edu/v5/tutorials/topical/multitasking.html#mutexes for details.

Example

// Global variables for the robot's odometry, which the rest of the robot's
// subsystems will utilize
double odom_x = 0.0;
double odom_y = 0.0;
double odom_heading = 0.0;

// This mutex protects the odometry data. Whenever we read or write to the
// odometry data, we should make copies into the local variables, and read
// all 3 values at once to avoid errors.
mutex_t odom_mutex;

void odom_task(void* param) {
  while(true) {
    // First we fetch the odom coordinates from the previous iteration of the
    // odometry task. These are put into local variables so that we can
    // keep the size of the critical section as small as possible. This lets
    // other tasks that need to use the odometry data run until we need to
    // update it again.
    mutex_take(odom_mutex, MAX_DELAY);
    double x_old = odom_x;
    double y_old = odom_y;
    double heading_old = odom_heading;
       mutex_give(odom_mutex);

    double x_new = 0.0;
    double y_new = 0.0;
    double heading_new = 0.0;
    
    // --- Calculate new pose for the robot here ---

    // Now that we have the new pose, we can update the global variables
    mutex_take(odom_mutex, MAX_DELAY);
    odom_x = x_new;
    odom_y = y_new;
    odom_heading = heading_new;
    mutex_give(odom_mutex);
    
    delay(10);
  }
}

void chassis_task(void* param) {
  while(true) {
    // Here we copy the current odom values into local variables so that
    // we can use them without worrying about the odometry task changing say,
    // the y value right after we've read the x. This ensures our values are
    // sound.
    mutex_take(odom_mutex, MAX_DELAY);
    double current_x = odom_x;
    double current_y = odom_y;
    double current_heading = odom_heading;
    mutex_give(odom_mutex);
    
    // ---- Move the robot using the current locations goes here ----
    
    delay(10);
  }
}

void initialize() {
  odom_mutex = mutex_create();

  task_create(odom_task, NULL, TASK_PRIORITY_DEFAULT, TASK_STACK_DEPTH_DEFAULT, "Odometry Task");
  task_create(chassis_task, NULL, TASK_PRIORITY_DEFAULT, TASK_STACK_DEPTH_DEFAULT, "Chassis Task");
}

bool mutex_take(mutex_t mutex, uint32_t timeout)

#include <pros/rtos.h>

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.

Example

// Global variables for the robot's odometry, which the rest of the robot's
// subsystems will utilize
double odom_x = 0.0;
double odom_y = 0.0;
double odom_heading = 0.0;

// This mutex protects the odometry data. Whenever we read or write to the
// odometry data, we should make copies into the local variables, and read
// all 3 values at once to avoid errors.
mutex_t odom_mutex;

void odom_task(void* param) {
  while(true) {
    // First we fetch the odom coordinates from the previous iteration of the
    // odometry task. These are put into local variables so that we can
    // keep the size of the critical section as small as possible. This lets
    // other tasks that need to use the odometry data run until we need to
    // update it again.
    mutex_take(odom_mutex, MAX_DELAY);
    double x_old = odom_x;
    double y_old = odom_y;
    double heading_old = odom_heading;
       mutex_give(odom_mutex);

    double x_new = 0.0;
    double y_new = 0.0;
    double heading_new = 0.0;
    
    // --- Calculate new pose for the robot here ---

    // Now that we have the new pose, we can update the global variables
    mutex_take(odom_mutex, MAX_DELAY);
    odom_x = x_new;
    odom_y = y_new;
    odom_heading = heading_new;
    mutex_give(odom_mutex);
    
    delay(10);
  }
}

void chassis_task(void* param) {
  while(true) {
    // Here we copy the current odom values into local variables so that
    // we can use them without worrying about the odometry task changing say,
    // the y value right after we've read the x. This ensures our values are
    // sound.
    mutex_take(odom_mutex, MAX_DELAY);
    double current_x = odom_x;
    double current_y = odom_y;
    double current_heading = odom_heading;
    mutex_give(odom_mutex);
    
    // ---- Move the robot using the current locations goes here ----
    
    delay(10);
  }
}

void initialize() {
  odom_mutex = mutex_create();

  task_create(odom_task, NULL, TASK_PRIORITY_DEFAULT, TASK_STACK_DEPTH_DEFAULT, "Odometry Task");
  task_create(chassis_task, NULL, TASK_PRIORITY_DEFAULT, TASK_STACK_DEPTH_DEFAULT, "Chassis Task");
}

bool mutex_give(mutex_t mutex)

#include <pros/rtos.h>

Unlocks a mutex.

See https://pros.cs.purdue.edu/v5/tutorials/topical/multitasking.html#mutexes for details.

Example

// Global variables for the robot's odometry, which the rest of the robot's
// subsystems will utilize
double odom_x = 0.0;
double odom_y = 0.0;
double odom_heading = 0.0;

// This mutex protects the odometry data. Whenever we read or write to the
// odometry data, we should make copies into the local variables, and read
// all 3 values at once to avoid errors.
mutex_t odom_mutex;

void odom_task(void* param) {
  while(true) {
    // First we fetch the odom coordinates from the previous iteration of the
    // odometry task. These are put into local variables so that we can
    // keep the size of the critical section as small as possible. This lets
    // other tasks that need to use the odometry data run until we need to
    // update it again.
    mutex_take(odom_mutex, MAX_DELAY);
    double x_old = odom_x;
    double y_old = odom_y;
    double heading_old = odom_heading;
       mutex_give(odom_mutex);

    double x_new = 0.0;
    double y_new = 0.0;
    double heading_new = 0.0;
    
    // --- Calculate new pose for the robot here ---

    // Now that we have the new pose, we can update the global variables
    mutex_take(odom_mutex, MAX_DELAY);
    odom_x = x_new;
    odom_y = y_new;
    odom_heading = heading_new;
    mutex_give(odom_mutex);
    
    delay(10);
  }
}

void chassis_task(void* param) {
  while(true) {
    // Here we copy the current odom values into local variables so that
    // we can use them without worrying about the odometry task changing say,
    // the y value right after we've read the x. This ensures our values are
    // sound.
    mutex_take(odom_mutex, MAX_DELAY);
    double current_x = odom_x;
    double current_y = odom_y;
    double current_heading = odom_heading;
    mutex_give(odom_mutex);
    
    // ---- Move the robot using the current locations goes here ----
    
    delay(10);
  }
}

void initialize() {
  odom_mutex = mutex_create();

  task_create(odom_task, NULL, TASK_PRIORITY_DEFAULT, TASK_STACK_DEPTH_DEFAULT, "Odometry Task");
  task_create(chassis_task, NULL, TASK_PRIORITY_DEFAULT, TASK_STACK_DEPTH_DEFAULT, "Chassis Task");
}

void mutex_delete(mutex_t mutex)

#include <pros/rtos.h>

Deletes a mutex.

Example

mutex_t mutex = mutex_create();
// Acquire the mutex; other tasks using this command will wait until the mutex is released
// timeout can specify the maximum time to wait, or MAX_DELAY to wait forever
// If the timeout expires, "false" will be returned, otherwise "true"
mutex_take(mutex, MAX_DELAY);
// do some work
// Release the mutex for other tasks
mutex_give(mutex);
// Delete the mutex
mutex_delete(mutex);

enum task_state_e_t

#include <pros/rtos.h>

The state of a task.

enum notify_action_e_t

#include <pros/rtos.h>

brief The action to take when a task is notified.

typedef void* task_t

#include <pros/rtos.h>

An opaque type that pontis to a task handle.

This is used for referencing a task.

typedef void(*task_fn_t)(void*)

#include <pros/rtos.h>

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* mutex_t

#include <pros/rtos.h>

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.

#define CURRENT_TASK

#include <pros/rtos.h>

The task handle of the currently running task.

#define TASK_PRIORITY_MAX

#include <pros/rtos.h>

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

#include <pros/rtos.h>

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_PRIORITY_DEFAULT

#include <pros/rtos.h>

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_STACK_DEPTH_DEFAULT

#include <pros/rtos.h>

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

#include <pros/rtos.h>

The minimal stack size for a task.

This equates to 512 words, or 2,048 bytes.

#define TASK_NAME_MAX_LEN

#include <pros/rtos.h>

The maximum number of characters allowed in a task's name.

#define TIMEOUT_MAX

#include <pros/rtos.h>

The maximum timeout value that can be given to, for instance, a mutex grab.