Task: Multithreading

The goal of this assignment is to learn and understand the mechanisms of multithreading and concurrency programming. You will use the functionality of the POSIX standard for that and learn about how POSIX manages the creation, handling, and termination of threads.

We decided to show you the aspects of multithreading via a simple ASCII game. You can see if you have done something right by observing that the game is getting more playable. In the beginning, you will only see a plain game map without any content.

The game is a simplified version of seaquest. Your player can move around and pick up divers. In the game the player needs to pick up all divers and rescue them, while avoiding debris and sharks in the water.

The game consists of 5 different entities:

• Debris: Debris are a 2×2 square on the game map. They are stationary and will kill your player immediately upon contact. (represented by a ‘M’)
• Sharks: Sharks are a single field on the game map and are moving randomly. They will destroy the player upon contact. (represented by an ‘S’)
• Player: The player (represented by a ‘P’)  gets moved via the WASD keys. The game shall quit when ‘q’ is pressed, when the hits an enemy or the border or the oxygen supply is depleted. (Lifepoints get set to 0)
• Divers: To get points, the player needs to rescue divers (represented by ‘D’). First the player needs to collect all missing divers in the water, then the divers need to be returned to the surface. After the divers are returned to the surface a new set of divers is spawned, which need to be rescued.
• Oxygen: While below a certain depth level the player loses oxygen. When the oxygen is depleted the player loses the game. To restore the oxygen level, the players needs to be near the surface.

When you open the folder of this task, you will notice five files:

• Makefile: Use this file to compile and run the program or clean up the folder with it. You MUST NOT commit any changes to this file!
• main.c: This file exists to more easily mount our testcases. You MUST NOT commit any changes to this file!
• searescue.h: This file contains relevant includes, typedefs, predefined values. You can change them as you wish but be careful: you MUST NOT commit changes to this file. Therefore, all changes are irrelevant for us.
• helpers.c: This file contains helper functions to make the game playable. You MUST NOT commit any changes to this file!
• searescue.c: This is the only file that will be checked and used by the test system. Please follow the TODOs and ONLY change and add code between TODO BEGIN and TODO END!

To summarize, you can modify all files but only are allowed to commit changes to searescue.c. This ensures that you are using the same files as the testsystem and everything should work locally as it would on the testsystem.

You must not create ANY global variables, delete existing code outside of the TODOs (comments can be changed and added, of course), or rearrange existing code! Be careful, do not delete any needed functions declared in the header file.

Furthermore, you should keep the lifetime of variables in mind and you shouldn’t leak any memory that you allocate. You don’t need to test this with valgrind since libncurses leaks memory and therefore valgrind would produce wrong results. Furthermore, valgrind is known to have bugs with this type of game and some of our TODOs.

What to do before you start?

• Pull from upstream!
• Carefully look at the TODOs in the searescue.c file.
  • The TODOs are enumerated in the suggested way you should solve the assignment
• Look at the Manpage and what those parameters of the needed functions are for and how they are used. (pthread_create( ... ), pthread_cancel( ... ), pthread_join( ... ), etc [https://man7.org/linux/man-pages/man7/pthreads.7.html])
• Only begin if you understand the basic concept, what a thread is, and what it does. Bruteforcing will lead to a severe amount of wasted time.
  • Try to understand the different functions in the searescue.c file and their connections.
  • Hint: Make sure that you reuse as many variables as possible.

You find all the needed information on the manual pages. You can access them by either typing man into the terminal or by reading them on various websites. For example, the manual for pthread_create( ... ) may be accessed by the command man pthread_create . For this exercise, you might find the following links helpful.

Debugging:

In this course, it’s very important to find errors yourself and notice issues in your own usage of syscalls or other functions. Therefore we recommend getting comfortable with a debugger, especially since most of you will take OS in the next semesters!

Debugging with VSCode

Manpages:

• pthreads in general
• pthread_create()
• pthread_join()
• pthread_cancel()

In case you prefer a german source:

• Linux-UNIX-Programmierung von Jürgen Wolf (chapter 10)

If you need a rough overview of the pthread library, make sure to check out the pthread tutorial by Peter C. Chapin. It contains a lot of information you might need for the first and second assignments.

Modify searescue.c in your git repository. You can find this file in the directory A1. Tag the submission with A1 and push it to the server. Do not add any additional files to the folder!

If you have any questions regarding this assignment, go to discord and read through the SLP channels. The probability that your question was already answered or some discussions will lead you in the right direction is quite high. If not so, just ask in the corresponding channel.

Sebastian Felix, sebastian.felix@student.tugraz.at

Thomas Knoll, thomas.knoll@student.tugraz.at