~mil/mepo

e17efef7646868ec70d181f4e3a20c1a9ea2e54c — Miles Alan a month ago a9d1c0f
Add notes on concurrency model to development guide
1 files changed, 35 insertions(+), 0 deletions(-)

M doc/developguide.md
M doc/developguide.md => doc/developguide.md +35 -0
@@ 26,3 26,38 @@ Run all files through zig fmt:
```sh
ag -g zig | xargs zig fmt
```

## Hacking Guide: Concurrency Model

## Interactive mode

While running in interactive mode, there's essentially 1-3 threads used by
Mepo. The underlying datastructure that manages thread-saftey is the
`QueueHashMap` which is used by the TileCache's lifo, transfer map, and
texture map and uses mutex's around Zig's `ArrayHashMap`.

The three threads used in interactive mode are:

1. The primary SDL thread (always present)
2. The downloading thread (`TileCache.thread_download`, present if set_network true)
3. The bbox queueing thread  (`TileCache.thread_queuebbox`, present while queueing a bbox)

(1) is always present from when you launch the application. (2) may be toggled
on and off given the `set_network` function. And (3) may be toggled on or off
given the `set_queue` function.

If (3) is present, you can assumed (2) is present - e.g. no queueing can take
place if there's no download thread.

The reason (3)'s logic is managed in a seperate thread is that given a bbox,
we need to convert all coordinates into the queue. This takes time because you
can for example queue the entire globe if desired.

### Noninteractive mode

While running in noninteractive mode (with `-d`), the application runs
as simple single-threaded application. Basically non-interactive mode is
just a hook into the downloading thread (2) mentioned above. Before starting
the downloading thread, the bounding-box is queued (non-concurrently,
in contrast to in interactive mode in which queueing and downloading
happens simulatenously).