Creating vs. Constructing

Most TI-RTOS modules commonly have _create() and _construct() APIs to initialize primitive instances. The main runtime differences between the two APIs are memory allocation and error handling.

Create APIs perform a memory allocation from the default TI-RTOS heap before initialization. As a result, the application must check the return value for a valid handle before continuing.

Listing 1. Creating a Semaphore
 1Semaphore_Handle sem;
 2Semaphore_Params semParams;
 3
 4Semaphore_Params_init(&semParams);
 5sem = Semaphore_create(0, &semParams, NULL); /* Memory allocated in here */
 6
 7if (sem == NULL) /* Check if the handle is valid */
 8{
 9    System_abort("Semaphore could not be created");
10}

Construct APIs are given a data structure with which to store the instance’s variables. As the memory has been pre-allocated for the instance, error checking may not be required after constructing.

Listing 2. Constructing a Semaphore
1Semaphore_Handle sem;
2Semaphore_Params semParams;
3Semaphore_Struct structSem; /* Memory allocated at build time */
4
5Semaphore_Params_init(&semParams);
6Semaphore_construct(&structSem, 0, &semParams);
7
8/* It's optional to store the handle */
9sem = Semaphore_handle(&structSem);