Table of Contents
Objectives
- Deal with technical debt
- Learn to multitask in C
- Create a POSIX thread with arguments
Introduction
One of the last fundamentals to know about programming in general is how to make your program do multiple things at once. Until this point, we have written single-threaded programs. This means that our programs have only followed a single path of execution while it runs (i.e., the program can only focus on one task at a time). However, many of the problems that we solve in the real-world are much more complex and may require us to interact with many facets of the problem simultaneously. In the lab for this class, creating a useful smart doorbell is definitely one of those multifaceted problems. Consider the following:
-
How can I upload my photo to the server while viewing it?
-
How can I actively be monitoring the status of my upload while also drawing to my screen in a loop?
While considering the previous questions, you may have noticed that with your current skill set, these problems seem difficult to solve without a complex algorithm or multiple programs running at once. By using threads, we can sidestep a lot of this headache by grouping different tasks/functions into distinct threads and call them from our main thread.
Creating a Thread
Threads in Linux programming are known as POSIX threads (or pthreads for short). pthread_t is the data type used to uniquely identify a thread:
#include <pthread.h>
pthread_t my_thread;
This object is used inside a range of different functions found inside the pthread.h library. The most important function for this lab is pthread_create(), which allows us to spawn a new thread and provide the function that it will run. Consider the simple threading program below:
#include <stdio.h>
#include <unistd.h> // Library that includes sleep()
#include <pthread.h> // Library that includes pthreading types and functions
void *print_msg(void *unused)
{
while(1)
{
printf("I'm in a thread!\n");
sleep(2); // Sleeps for 2 seconds
}
return NULL;
}
int main()
{
pthread_t my_thread;
pthread_create(&my_thread, NULL, print_msg, NULL);
while(1)
{
printf("I'm in main!\n");
sleep(1);
}
return 0;
}
To compile using the pthread.h library, you will need to add -pthread to your normal gcc compile command.
Let’s take a closer look at what is going on in the pthread_create() function. The arguments that are expected in the function are as follows:
-
The address of your thread struct. This is how your program will know how to identify your thread in the program.
-
This argument expects a special
pthread_attr_tstruct pointer. Since we are covering the basics of threading in this class, this field is ignored by putting aNULLin its place. -
A pointer to the function we are calling. Function pointers can be provided by giving the name of the function. Make sure you only provide the name, and don’t call the function (e.g.,
print_msginstead ofprint_msg()). If you like, you can put a&in front of the function name to make it more obvious it’s a function pointer (e.g.,&print_msg), but this is not required by the compiler. -
A pointer you provide to this argument will be passed as an argument to the function you are running in the new thread. This is a great way to provide information to the new thread. Notice that for this example it is
NULLsince our function doesn’t require any special arguments. The next section has more information about how to pass arguments into a thread.
You’ll notice that both our main() function and our print_msg() function have while(1) loops that will run indefinitely. Because threading allows us to run different functions simultaneously, we will see output that looks something like this:
I'm in a thread!
I'm in main!
I'm in main!
I'm in a thread!
I'm in main!
I'm in main!
I'm in a thread!
I'm in main!
I'm in main!
I'm in a thread!
I'm in main!
I'm in main!
...
Passing in Arguments to a Thread
While the previous example may have been interesting in the sense that we’ve learned to use threads, it is pretty lackluster in the sense that we can’t get any information into or out of the thread. To do this, we will need to understand how to work with void * and allocating memory.
void *: The Generic Pointer
A void * is the generic pointer in C. It is used to store a memory address, but does not indicate the type of data stored at the address. This means that any type of pointer can be cast to or from a void * object. It is up to you, as the programmer, to know what you passed into the function and cast it to the correct pointer type. This datatype is very useful when using threading functions because it allows us to pass in the address of any type of data to the function we are spawning. The threading function also returns a void * data type, allowing it to pass back a pointer to any type of data. This accounts for why our print_msg() function in the previous example program’s return type was a void *.
Example
Consider the following program:
#include <stdio.h>
#include <unistd.h> // Library that includes sleep()
#include <stdlib.h> // Library that includes malloc()
#include <pthread.h> // Library that includes pthreading types and functions
void *print_num(void *arg)
{
while(1)
{
// Notice that we have to cast the void * back to an int * and then we use the * to get the value inside
printf("The number is:\t%d\n", *((int *) arg));
sleep(2); // Sleeps for 2 seconds
}
return NULL;
}
int main()
{
int *i = (int *)malloc(sizeof(int)); // Create an int pointer and give it enough space to hold an int.
*i = 0; // Set the value inside the pointer to 0
pthread_t my_thread;
// Notice that we have to cast i to a void *
pthread_create(&my_thread, NULL, print_num, (void *) i);
while(1)
{
*i = (*i) + 1; // Increment the value inside of i
printf("I'm in main!\n");
sleep(1);
}
return 0;
}
Let’s take a closer look at this code example. The pthread_create() function is spawning a new thread to run the print_num function. We want to pass an integer to this function. Since we always use a void * to pass data to a function run by pthread_create(), we need to allocate memory for an integer and provide it’s address as the last argument to pthread_create().
You’ll notice some things about how we’ve done this:
-
We have allocated the space for the integer using
malloc. While we could have simply declared an integer (int i;), this would create the integer on the stack. In general, it’s bad practice to pass addresses on the stack to other threads as they may continue to execute after stack variable goes out of scope. Another alternative tomallocis to declare the integer as a global variable. -
To set the value of the integer to zero, we needed to refer to the pointer’s contents:
*i = 0; -
When we passed it into
pthread_create(), we needed to cast it from aint *to avoid *.
Now that we have provided the address of our integer to pthread_create(), let’s take a look at how it is received by the print_num() function:
-
The address is provided as an argument to the function with type
void *. -
To use
argwe need to do two things:-
Cast
argback into the type that we expect (in this case anint *). -
Deference it with a
*to get the integer value pointed to by this address (the*in front of the cast statement).
-
Return Values from Threads
To get a return value from a thread in C, you would need to use the pthread_join() function. For the purposes of this lab, we will not be using pthread_join(), but you can read more about it in the Explore More! section. pthread_join() is NOT recommended for this lab.
Procedure
Requirements
- In order to use the threading library, you need to include the library in your source code and in your Makefile.
- Add
#include <pthread.h>and#include <unistd.h>tomain.cwith your other headers. - Add
-pthreadto theCFLAGSvariable in your Makefile. - Before you go any farther, try
makeon your project to verify everything is still working.
- Add
-
Write a function called
send_image. This function should connect to the server, send the image, receive the response, and close the socket. You need to figure out the correct function signature (return type and arguments) for this function. You will likely want to pass the image buffer as an argument and free the image buffer within this function when sending is complete. -
Run your code using this newly created
send_imagefunction (not using threads) to verify that everything still works as expected. Notice that sending data to the server is slow and that the menu gets blocked while waiting for the send to complete. - Instead of calling
send_imagedirectly, create a thread for this function.-
Now that calling
send_imageis no longer blocking, make sure that you are not callingfreeon the image buffer right after the thread is started. -
Warning: you should not call any display functions in a thread. The display functions are not thread-safe, meaning that if multiple threads call the same function, weird things can happen. You should only call the display functions in your main loop.
-
- Create a status bar the size of your highlight bar at the bottom of the screen with a blue background:
-
Consider adding the status bar code to your draw menu function.
-
When your image is being sent in a thread, the status bar text should say “Sending…” with a blue background.
-
When your image is sent successfully (i.e. after calling
client_close), change the color of the status bar to green and show “Sent!” as the text. How will the main thread (which is displaying the status bar) know when the send image thread is done sending? A global status variable set by the send image thread may be helpful. -
The status bar should stay green with the sent message for 2 seconds. After the 2 seconds, hide the status bar. How do you know when it has been 2 seconds? Consider adding a call to
delay_msin yoursend_imagefunction before updating the status variable to a hide state.
-
- Ensure that your menu is still responsive and that you can navigate the menu while the status bar is visible.
Here is a demo showing the different features of the lab:
Pass Off & Submission
- Your program must compile without warnings or errors. Your
Makefilehas the-Werrorflag to ensure that it doesn’t have errors. - Pass off with a TA by demonstrating that your main program running on the doorbell fulfills all the requirements outlined above.
- Take the Pass off Quiz on Learning Suite.
- Follow the instructions in the
README.mdfile in the repository. Add the requested detail about features and usage to this file. - Make sure to push your changes back to your Git remote repository. Follow the instructions on the Lab Setup page.