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 //! # Thread manager
//! //!
//! This module describes the data structure and the methods used for thread scheduling //! 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 //! in the BurritOS operating system. A struct named [`ThreadManager`] holds the list of
//! all existing threads and synchronization objects, such as `Locks`, `Semaphores` and //! all existing [`Thread`] instances and synchronization objects, such as
//! `Conditions`. //! [`Lock`](crate::kernel::synch::Lock),
//! [`Semaphore`](crate::kernel::synch::Semaphore) and
//! [`Condition`](crate::kernel::synch::Condition).
//! //!
//! ## Purpose //! ## 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 //! ### Two lists of threads
//! //!
@ -24,21 +26,23 @@
//! //!
//! Locks, Semaphores and Conditions allow resource sharing among running threads. Since resources //! 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 //! 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 //! threads that a resource may be busy or unavailable; say for example that:
//! 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 //! - Thread **A** wants to write to a file while **B** is currently reading said file.
//! avoid such issues. Thread **A** will have to wait for **B** to finish reading the 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 //! 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 //! 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 //! ## Usage
//! //!
//! `ThreadManager` is thought as a subcomponent of the `System` struct. Instanciating //! [`ThreadManager`] is thought as a subcomponent of the [`System`](crate::kernel::system::System) struct.
//! `System` will automatically instanciate a `ThreadManager` //! 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: //! this:
//! //!
//! ``` //! ```
@ -62,8 +66,8 @@
//! //!
//! ## Imports //! ## Imports
//! //!
//! The `List` and `ObjAddr` submodules used in this module are defined in the utility //! 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 //! module. The source code of [`ObjAddr`] has been decoupled from thread_manager in an effort
//! to keep this module concise. //! to keep this module concise.
use std::{ use std::{