---
# System prepended metadata

title: Warmup Exercises

---

# Warmup Exercises

This document is for those who want to "get their hands dirty" on TSan. Here are some simple exercises.

### Exercise 0: Build LLVM+TSan and Benchmarks

References:
* [Build LLVM+TSan](/c9own0pxTI65M5areov27w)
* [OpenMP Benchmarks (and some others)](/xeC9oSkHTsemZjAdDRGoCw)
* [Chromium/V8](/1pjMkN2mSBaull8ylWgcbg)
* [DBMS + Benchbase](/Xx9CdNCUSC6YokIXumJcwA)

There are also many [test cases](https://github.com/llvm/llvm-project/tree/987087df90026605fc8d03ebda5a1cd31b71e609/compiler-rt/test/tsan) in the TSan codebase.


### Exercise 1: Log all events

Choose a program above and modify TSan to print out all events (memory access and synchronization).

:::info
This helps you get familiar with the event handlers in TSan.
:::


### Exercise 2: Implement sampling

In sampling-based race detection, we only want to analyse some of the events, in order to lower the analysis overhead.

There are various sampling strategies. For example, use a PRNG to sample 5% of the events for analysis (i.e. skip 95% of the events).

:::warning

Where is the right code location to do this? Why does it work/not work at certain locations?
:::

:::info
This lets you investigate deeper into how the handlers are implemented in TSan, the data structures involved, and the potential impact in performance when modifying these handlers.
:::

Consider another sampling strategy.


### Exercise 3: Implement tree clocks

Find the `VectorClock` class and modify it to support tree clocks.

References:
- [Paper](https://www.comp.nus.edu.sg/~umathur/papers/tree-clocks-asplos22.pdf)
- [RAPID](https://github.com/focs-lab/rapid/commit/08eb055be983f075427d2aa0762f08b684fba54c#diff-e203956889335f6a1377b37bc071952753b43a7bfe4059bfbbd431b8f9871f3c)
- [Arboreta](https://github.com/verse-lab/arboreta/blob/main/race-detector/detector/treeclock_ptr.c)


:::warning
This is likely not so straightforward.

Try a program that runs for a very long time and with a known bug (e.g. modify a JS test case to loop many times). You might face a soundness issue.

(I am not sure if the JS recommendation will expose the issue. I only managed to trigger it when running Blender to render a video after a few minutes. I don't have the reproduction steps at the moment.)
:::

:::info
This lets you investigate deeper into how the synchronization handlers are implemented in TSan, and how a thread's local epoch is updated.
:::

