How benzakariae03/codexion works
1. Repository shape
- This is a single native C executable, codexion, built with make.
- The architecture is a thread-based simulation, not a distributed system: one process spawns multiple coder threads plus a monitor thread.
2. Entry point and startup flow
- main.c drives the program lifecycle.
- validation.c checks CLI arguments and mode selection (fifo or edf).
- init.c builds the runtime state from the parsed inputs, then threads_creation.c starts the worker threads.
3. Core domain model
- codexion.h is the central contract for shared structs, constants, and function prototypes.
- The main entities are:
- coder state
- dongle/resource state
- global simulation state
- scheduling/queue state
- This header is the boundary between the modules that manage parsing, scheduling, threading, and teardown.
4. Worker subsystem: coder behavior
- coder_routine.c implements each coder thread’s lifecycle.
- A coder repeatedly acquires two dongles, performs compile/debug/refactor phases, and decrements its remaining compile count.
- The routine also checks the shared shutdown flag so a coder can exit cleanly when the simulation ends.
5. Resource arbitration subsystem
- fifo_scheduler.c, edf_scheduler.c, and queue.c handle contention for dongles.
- Each dongle appears to maintain its own wait structure, so the resource layer is per-dongle rather than one global lock.
- FIFO serves waiting coders in arrival order; EDF reorders them by urgency, based on how close a coder is to burnout.
6. Synchronization boundaries
- The project relies on pthread_mutex_t and pthread_cond_t to protect shared state and avoid busy-waiting.
- status_mutex-style protection covers simulation flags and counters.
- log.c uses a dedicated mutex so log lines remain coherent across threads.
- Individual dongles also have their own synchronization so ownership changes are serialized.
7. Deadlock avoidance strategy
- The simulation prevents circular wait by varying acquisition order: odd coders take one dongle first, even coders take the other first.
- This keeps the resource graph from forming the classic “everyone holds one, waits for the second” deadlock pattern.
8. Monitor subsystem
- monitor_routine.c is the supervisory thread.
- It periodically checks coder timing state to detect burnout and ignores coders that already finished.
- On burnout, it flips the global termination flag so the rest of the system can stop.
9. Timing and waiting
- precise_sleep.c provides millisecond-level sleeping without excessive CPU use.
- Waiting is cooperative: coders and the monitor both wake up to re-check shared state rather than spinning.
- The README indicates pthread_cond_timedwait is used so sleepers can also respond to cooldown expiry and shutdown.
10. Logging and observability
- log.c centralizes output formatting: <timestamp_ms> <coder_id> <action>.
- The logger is mutex-protected, so concurrent thread output does not interleave.
- The only message allowed after end-of-simulation conditions is burnout reporting.
11. Cleanup and shutdown
- clean_up.c owns teardown of mutexes, condition variables, and allocated runtime objects.
- The shutdown path is shared: once the monitor or completion logic marks the simulation over, coder threads stop, release resources, and join back before cleanup completes.
12. Utility and parsing helpers
- ft_atol.c and codexion_utils.c support numeric parsing and small shared helpers.
- validation.c and these utilities form the input boundary, keeping the simulation logic separate from CLI concerns.
13. How data moves through the system
- CLI arguments flow into validation, then into initialization.
- Initialization creates shared state and per-coder/per-dongle runtime objects.
- Thread creation hands those objects to the coder and monitor routines.
- Coders mutate shared resource state under locks; the monitor reads the same state to decide when to stop the simulation.
- Cleanup consumes the same shared objects after all threads have exited.
14. Best diagram takeaway
- The clearest architecture diagram would show one process with:
- a main/init/control lane,
- N coder threads contending for per-dongle resources,
- one monitor thread watching shared timing state,
- a shared synchronization/logging layer in the middle,
- and a cleanup/termination path that is triggered by either completion or burnout.
Main entry points: coder_routine.c Coder routine · monitor_routine.c Monitor · init.c Init runtime · clean_up.c Cleanup
Components 18
Startup & control
CLI entry, validation, initialization, and thread launch.
- main · Program entry and lifecycle driver.
coders/main.c - Validate args · Checks CLI inputs and selects simulation mode.
coders/validation.c - Parse numbers · Converts string inputs into numeric configuration values.
coders/ft_atol.c - Helpers · Small utility functions used across the executable.
coders/codexion_utils.c - Init runtime · Builds the simulation state from validated inputs.
coders/init.c - Start threads · Creates coder workers and the monitor thread.
coders/threads_creation.c
Worker runtime
Coder threads, monitor thread, and their scheduling/resource flow.
- Coder routine · Acquires two dongles, runs phases, and decrements work remaining.
coders/coder_routine.c - FIFO scheduler · Serves waiting coders in arrival order.
coders/fifo_scheduler.c - EDF scheduler · Prioritizes coders by urgency / burnout proximity.
coders/edf_scheduler.c - Wait queue · Per-dongle waiting structure used by the schedulers.
coders/queue.c - Monitor · Watches coder timing state and triggers global stop on burnout.
coders/monitor_routine.c
Shared state
Central contract and synchronization/logging utilities shared by threads.
- codexion.h · Central header for structs, constants, and prototypes.
coders/codexion.h - Sim state · Shared simulation flags, counters, and timing state.
- Dongles · Per-resource ownership and waiting state for contention.
- Sync layer · Mutexes and condition variables protecting shared progress.
- Logger · Serialized action output from concurrent threads.
coders/log.c - Timed wait · Millisecond sleep and cooperative waiting primitives.
coders/precise_sleep.c
Shutdown & teardown
Termination path and object cleanup.
- Cleanup · Destroys mutexes, condition variables, and allocated runtime objects.
coders/clean_up.c
Connections 28
- main → Validate args: parse CLI · Main validates arguments and mode selection before setup.
- Validate args → Parse numbers: convert values · Validation relies on numeric parsing for configuration fields.
- Validate args → Helpers: shared checks · Validation uses helper routines for common input handling.
- main → Init runtime: bootstrap · Initialization runs after successful validation.
- Init runtime → codexion.h: build state · Runtime structures are created according to the shared contract.
- Init runtime → Sim state: create · Initializes global simulation flags and counters.
- Init runtime → Dongles: create · Allocates per-dongle resource state and ownership data.
- Init runtime → Start threads: launch · Hands initialized objects to thread creation.
- Start threads → Coder routine: spawn · Starts one worker thread per coder.
- Start threads → Monitor: spawn · Starts the supervisory monitor thread.
- Coder routine → FIFO scheduler: request resources · Coder threads contend through the FIFO scheduler when enabled.
- Coder routine → EDF scheduler: request resources · Coder threads contend through the EDF scheduler when enabled.
- FIFO scheduler → Wait queue: use · FIFO scheduling is backed by a per-resource wait queue.
- EDF scheduler → Wait queue: use · EDF scheduling reorders the same waiting structure by urgency.
- Wait queue → Dongles: attach · Each dongle maintains its own waiting and ownership state.
- Coder routine → Dongles: lock & release · Worker threads acquire and release dongles under synchronization.
- Coder routine → Sync layer: protect shared state · Workers coordinate through mutexes and condition variables.
- Monitor → Sim state: inspect · Monitor reads timing and completion state to decide when to stop.
- Monitor → Coder routine: observe · Supervises coder progress and burnout timing.
- Monitor → Logger: report · Burnout and state changes are logged in a serialized way.
- Coder routine → Logger: emit actions · Coder actions are written through the thread-safe logger.
- Coder routine → Timed wait: wait · Coders sleep cooperatively between work phases and checks.
- Monitor → Timed wait: poll interval · Monitor wakes periodically rather than spinning.
- Coder routine → Sim state: check shutdown · Workers exit cleanly when the global termination flag is set.
- Monitor → Cleanup: trigger stop · Burnout detection flips the termination path that leads to teardown.
- Coder routine → Cleanup: join after stop · Workers release resources and exit before cleanup completes.
- main → Cleanup: finalize · Main completes shutdown and teardown after threads finish.
- Cleanup → codexion.h: destroy · Teardown walks the same shared objects defined by the contract.