From f6195a9da0f8d7152505150f73c9edd3c06be982 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Autin?= Date: Thu, 20 Apr 2023 15:15:11 +0200 Subject: [PATCH] Updated thread_manager module documentation --- src/kernel/thread_manager.rs | 32 ++++++++++++++++++-------------- 1 file changed, 18 insertions(+), 14 deletions(-) diff --git a/src/kernel/thread_manager.rs b/src/kernel/thread_manager.rs index 2de0449..654f4e8 100644 --- a/src/kernel/thread_manager.rs +++ b/src/kernel/thread_manager.rs @@ -1,13 +1,15 @@ //! # Thread manager //! //! This module describes the data structure and the methods used for thread scheduling -//! in the BurritOS operating system. A struct named `ThreadManager` holds the list of -//! all existing threads and synchronization objects, such as `Locks`, `Semaphores` and -//! `Conditions`. +//! in the BurritOS operating system. A struct named [`ThreadManager`] holds the list of +//! all existing [`Thread`] instances and synchronization objects, such as +//! [`Lock`](crate::kernel::synch::Lock), +//! [`Semaphore`](crate::kernel::synch::Semaphore) and +//! [`Condition`](crate::kernel::synch::Condition). //! //! ## Purpose //! -//! `ThreadManager` holds the state of the system processes using the following subcomponents: +//! [`ThreadManager`] holds the state of the system processes using the following subcomponents: //! //! ### Two lists of threads //! @@ -24,21 +26,23 @@ //! //! Locks, Semaphores and Conditions allow resource sharing among running threads. Since resources //! can only be accessed by a single thread at a time, we need data structures to signal other -//! threads that a resource may be busy or unavailable; say for example that thread **A** wants to -//! write to a file while **B** is currently reading said file. Thread **A** mutating the state of -//! the file could cause issues for **B**. Therefore **B** needs to lock the file in question to -//! avoid such issues. Thread **A** will have to wait for **B** to finish reading the file. +//! threads that a resource may be busy or unavailable; say for example that: +//! +//! - Thread **A** wants to write to a file while **B** is currently reading said file. +//! - Thread **A** mutating the state of the file could cause issues for **B**. +//! - Therefore **B** needs to lock the file in question to avoid such issues. +//! - Thread **A** will have to wait for **B** to finish reading the file. //! //! These synchronization objects are held in an instance of the ObjAddr structure held by //! ThreadManager. Their state is mutated depending on the actions of the currently running thread -//! through methods such as `ThreadManager::sem_p`. +//! through methods such as [`ThreadManager::sem_p`]. //! //! ## Usage //! -//! `ThreadManager` is thought as a subcomponent of the `System` struct. Instanciating -//! `System` will automatically instanciate a `ThreadManager` +//! [`ThreadManager`] is thought as a subcomponent of the [`System`](crate::kernel::system::System) struct. +//! Instanciating [`System`](crate::kernel::system::System) will automatically instanciate a [`ThreadManager`] //! -//! Manually loading a Thread into ThreadManager to execute a program with BurritOS could look like +//! Manually loading a [`Thread`] into [`ThreadManager`] to execute a program with BurritOS could look like //! this: //! //! ``` @@ -62,8 +66,8 @@ //! //! ## Imports //! -//! The `List` and `ObjAddr` submodules used in this module are defined in the utility -//! module. The source code of ObjAddr has been decoupled from thread_manager in an effort +//! The [`List`] and [`ObjAddr`] submodules used in this module are defined in the utility +//! module. The source code of [`ObjAddr`] has been decoupled from thread_manager in an effort //! to keep this module concise. use std::{