Task Creation and Semaphore Tutorial

[slavik262]

Someone asked for help with Task creation and semaphores here, but I think this warrants its own thread.

Due to my work in other systems, I'm using task and thread interchangeably in this explanation. Sorry if this confuses anyone.

Task Creation and Arguments

To create a task, first write a task function (the function that will run in the separate thread). Note that this function will not automatically loop, so you'll need a loop structure unless you want it to do its work and exit immediately. I'll go over how to pass data into your function in a second.

To actually start the function in a different thread, create a Task class. The constructor takes a name for the class (pick whatever you want - this is just the name the task will have once created) as the first argument. The second argument is a function pointer to your task function. Use (FUNCPTR)myFunction, where myFunction is the name of your task function. This provides the memory address of where your function is located in the program so that the task can call it when it starts up. Leave the task priority and stack size (the last two arguments in the constructor) alone unless you know what you're doing. The defaults will work fine, and messing with the task priority can cause the program to behave unexpectedly.

To start your task, call the Start() method of the Task class you created. Start can take anywhere from 0 to 10 integer values, which are passed as arguments to the task function. Here's where things get fun:

Normally (in any other multithreading library I've used), thread/task functions take a void pointer as an argument. This lets you pass in a pointer to anything you want, and then use it in your function by just casting it back to its correct type. However, for whatever reason, VxWorks (the robot's Operating System) only allows you to pass in integers. If you're careful, you can trick your way around this and still do the same thing. You set an integer argument to the address of what you want to pass in, and cast it back to a pointer in the function. This works because the operating system the robot uses is a 32-bit OS, which means that its pointers are the same length as a 32-bit integer. An example follows.

Say you want a separate that spins a motor using a jaguar based on a joystick input (there's no reason why you couldn't just put it in the main task, but it's just an example). The entire process would be something like this:

Create a struct that contains all the data you'd need (in this case pointers to a Joystick and a Jaguar class).

struct SpinTaskArgs
{
     Joystick* joy;
     Jaguar* jag;
};

We'll also write our function for the task:

void MySpinTaskFn(UINT32 argPtr)
{
SpinTaskArgs* args = (SpinTaskArgs*)argPtr;

/*Do stuff with args, which is now a pointer to the
SpinTaskArgs struct you passed into the function*/
}

Notice how the function takes the integer argument and casts it into a pointer for your use. This will make more sense down the road.

In your main robot class, create an instance of this struct and set its members to point to their respective Joystick and Jaguar classes. Also create a task class

SpinTaskArgs spinArgs;
/*Assuming your joystick and jaguar are members of
the robot class and not allocated using the keyword new,*/
spinArgs.joy = &myJoystick;
spinArgs.jag = &myJaguar;

Task mySpinTask("SpinTask", (FUNCPTR)MySpinTaskFn);

Start up your task. We're going to pass the address of the SpinTaskArgs struct into the function as an integer, which is what the Start() function will accept. Notice now how this will work. To make VxWorks happy, you're passing the address of what you need in as an int, but it gets converted back to a pointer inside of your function.

mySpinTask.Start((UINT32)(&spinArgs));

Semaphores

Semaphores basically prevent two tasks from accessing the same variable/pointer at the same time. This is needed because if two or more tasks access the same data at the same time, the world ends (or at least the data can get corrupted and weird stuff can happen. )

To prevent this from happening, you can use critical regions around code that accesses shared data. Each piece of shared data (be it a variable, a struct, or a class) should have its own semaphore, and every part of your code that accesses it should have a critical region using that semaphore.

Say you have a vector of targets that you want to share between tasks.

Vector<Target> myTargets;

Create a semaphore using the type SEM_ID. I usually initialize the semaphores to binary ones using functions found in "semLib.h", but I'm pretty sure this isn't necessary.

SEM_ID targetSem;

WPILib provides a nice wrapper that automatically creates critical sections for you. So whenever you access your targets vector (or a pointer to it), surround the code with the following:

CRITICAL_REGION(targetSem)
/*code that accesses myTargets here*/
END_REGION

This way, only one critical region that uses targetSem will run at once. Others will stop execution and wait for the active critical region to exit.

If you have any more questions, I'd love to help. Shoot me an email or PM me.

[byteit101]

Unless you have fancy code, you should not encounter this (for the most part), but watch out for race conditions and locking.
if I have task A and it is running:

CRITICAL_REGION(Sem1)
Wait(5.0);//demo purposes
CRITICAL_REGION(Sem2)
/*Code here*/
END_REGION
END_REGION

and you have Task B running:

CRITICAL_REGION(Sem2)
Wait(5.0);//demo purposes
CRITICAL_REGION(Sem1)
/*Code here*/
END_REGION
END_REGION

Assuming they were started within 5 seconds of each other, they will both lock, and nothing will happen. Why?
Task A locks Sem1 and waits for 5 seconds, where Task B starts, and Locks Sem2
Task A has waited 5 seconds, and tries to lock Sem2, but Task B has it, so It waits for B to release it.
Meanwhile, B has waited its 5 seconds, and tries to Lock Sem1, but Task A has it so it waits for A to release it.
they are each waiting for the other to do something, so they do nothing

[taichichuan]

Be careful of using binary semaphores (via semBCreate) for mutual exclusion. There is a rather nasty problem known as priority inversion that can happen if you're not careful.

Binary semaphores are best used for synchronization like:

Forever() {
wait here until something happens;
do what must be done;
}

And in another piece of code:

signal that something must be done

That is, binary semaphores are usually found as a single instance (semTake in VxWorks or the synchronize method in the WPILib) and a semGive is located in another piece of code.

For mutual exclusion (i.e., to protect a piece of data from simultaneous access) the declaration would look more like:

m_mySemaphore = semMCreate(SEM_Q_PRIORITY | SEM_DELETE_SAFE | SEM_INVERSION_SAFE);

Then the use of the semaphore is more consistent with the WPILib

CRITICAL_REGION(m_mySemaphore);
...
END_REGION

construct.

Using a binary semaphore for mutual exclusion is what got NASA into trouble on Mars with the first rover (before Spirit, et al). They had to create a patch and use interpanetary FTP to upload it. Then they pressed the reset button from Earth and held their breath... Fortunately, it worked.

HTH,

Mike