Rativel/BurritOS
1
1
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Updated thread_manager module documentation

Browse Source
This commit is contained in:
François Autin 2023-04-20 15:15:11 +02:00
parent 597ffa753a
commit c278236d81
No known key found for this signature in database
GPG Key ID: 343F5D382E1DD77C
1 changed files with 18 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
src/kernel/thread_manager.rs
View File

@ -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::{