/Teaching/System Level Programming/Assignments/A1


Pull from upstream before solving this task.


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.

Please read the full description of this assignment carefully beforehand. You will need all of the information, which will save you a lot of time.

Main Idea

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.

In the game, you are stranded in deep space in your malfunctioning spaceship. Therefore, you need to collect supply crates in order to repair it. However, there are aliens who also want to retrieve those precious crates and will damage your spaceship if you dare to encounter them. Furthermore, there are stationary black holes which you will want to avoid.

The game consists of 3 different entities:

  • Black holes: Black holes are a 2×2 square on the game map. They are stationary and will kill your player immediately upon contact. (represented by a ‘B’)
  • Aliens: Aliens are a single field on the game map and are moving at medium speed. They will destroy your spaceship upon contact. (represented by an ‘A’)
  • Player: To collect supply crates and avoid enemies, the player (represented by an ‘P’)  gets moved via the WASD keys. The game shall quit when ‘q’ is pressed, when it hits an enemy or when it hits the border. (Lifepoints get set to 0)
  • Supply crates: To get points, you may collect some crates (represented by ‘#’). Once one artifact is collected, the current artifact should disappear on the map and the next artifact shall spawn immediately at a random position.

Setup

You’ll have to install ncurses on your system. In Debian/Ubuntu the following line will do the job:

sudo apt-get install libncurses6-dev libncursesw6-dev

In case ncursesw6 is not working or not available for your system, you may also use ncursesw5. If that’s the case, you may replace the line

NCURSES = $(shell ncursesw6-config --cflags --libs)

in the Makefile with the line:

NCURSES = $(shell ncursesw5-config --cflags --libs)

Do NOT make any other changes to the Makefile!

Implementation details

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

  • Makefile: Use this file to compile and run the program or clean up the folder with it.
  • spacecollector.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 functions, which make your implementation run. As with your header file, you can change everything in there, but as the header file, you MUST NOT commit any changes to this file as well, so your changes are irrelevant to the testing system.
  • spacecollector.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!

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.

What to do before you start?

  • Pull from upstream!
  • Carefully look at the TODOs in the spacecollector.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 spacecollector.c file and their connections.
    • Hint: Make sure that you reuse as many variables as possible.

I prepared some data structures to save some time. You can find them in the header file. There is a predefined structure for the parameters you have to pass. USE IT!

If you take a closer look into the usage of the game map array, you may recognize that there could occur several race conditions with the usage of this array. You do not have to worry about them. For readability of the given code and to just focus on the first learning goals of this course proper synchronization is left out. Occurring race conditions should not crash the program and for test runs on the test system, they are solved. How race conditions are preventable will be discussed in the Thread Synchronization assignment. If you want some further information, take a look at this page: https://en.wikipedia.org/wiki/Race_Condition.
However, you might encounter other race conditions with your implementation which do not reason in the usage of the game map array. If you notice such buggy behavior you are not allowed to use mutexes, semaphores, etc. Also, the usage of functions like sleep() is not the way to go here! Therefore additional calls to sleep functions and the usage of synchronization primitives are forbidden!

Helpful resources

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.

Manpages:

In case you prefer a german source:

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.

Submission

Modify spacecollector.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!

Assignment Tutor

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