diff --git a/Cargo.lock b/Cargo.lock index d1e502e..686e201 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -4,21 +4,15 @@ version = "0.1.0" dependencies = [ "chrono 0.9.0 (git+https://gitlab.com/CyberMages/chrono.git)", "scribe 0.1.0 (git+https://gitlab.com/CyberMages/scribe.git)", - "spellbook 0.1.0 (git+https://gitlab.com/CyberMages/spellbook.git)", ] [[package]] name = "chrono" version = "0.9.0" -source = "git+https://gitlab.com/CyberMages/chrono.git#10f1633ac1334cb6ada86222c68efeea89141be7" +source = "git+https://gitlab.com/CyberMages/chrono.git#3e428f71816c061ede6f6044fbf5f231e38d9b67" [[package]] name = "scribe" version = "0.1.0" source = "git+https://gitlab.com/CyberMages/scribe.git#e52418d3bfc28cd1f03cc7f31af06fce2e03f844" -[[package]] -name = "spellbook" -version = "0.1.0" -source = "git+https://gitlab.com/CyberMages/spellbook.git#f8526d248f3b7eb4f15f672368ac45a64c4eacbd" - diff --git a/Cargo.toml b/Cargo.toml index 3ad5776..9c9b2e3 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -6,7 +6,7 @@ description = "A Rust task scheduler." license = "" repository = "https://gitlab.com/CyberMages/apprentice.git" documentation = "" -keywords = ["scheduler", "task", "thread"] +keywords = ["apprentice", "scheduler", "task", "thread"] [dependencies.chrono] @@ -14,6 +14,3 @@ git = "https://gitlab.com/CyberMages/chrono.git" [dependencies.scribe] git = "https://gitlab.com/CyberMages/scribe.git" - -[dependencies.spellbook] -git = "https://gitlab.com/CyberMages/spellbook.git" diff --git a/README.md b/README.md index 8a51d8b..d14405d 100644 --- a/README.md +++ b/README.md @@ -1 +1,36 @@ # Apprentice # + A task based thread scheduling library. It will track and maintain +compute and blocking threads. The scheduler will then handle issuing tasks +amoung the threads it maintains. + +## Threads ## + Threads are implemented using the Rust standard library threads. These will +be managed by a scheduler. Each scheduler has two types of threads that it +distinguishes against. Blocking and Compute. + +### Blocking ### + Blocking threads are threads with tasks that will block while they are +being processed. Tasks that do not block can be run here as well if you need +to spawn more threads than the scheduler keeps alive for compute threads. +However, non blocking tasks would be better run on a compute thread. + +### Compute ### + Compute threads are threads with tasks that will never block. This is +a strict requirement that the programmer must adhere to. Compute threads and +task sharing will not work if all the available compute threads are blocked. + +## Tasks ## + Tasks are the thread safe portions of code that you wish to write. These +can be blocking or non blocking. If a task is marked as Immortal, then like +the pheonix, when it is finished processing the reset function will be called +and the task will be set to run again. By default, however, tasks are Mortal +and will not be reset and reprocessed. + +## Scheduler ## + The scheduler creates and maintains all the compute and blocking threads +it needs to run and processs tasks given to it. The scheduler will destroy +threads that it determines are not needed. You can create multiple schedulers +and each one will maintain its own set of threads and tasks. A single, program +wide scheduler, can be created and accessed by libraries that need to spawn +tasks as well. It is recommended to use this as your main scheduler and it +can be set and retieved by your program. diff --git a/src/lib.rs b/src/lib.rs index 638896f..26b7b5a 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,9 +1,6 @@ #[macro_use] extern crate scribe; -#[macro_use] -extern crate spellbook; - extern crate chrono; diff --git a/src/task_state.rs b/src/task_state.rs index 9adabfb..9621b8e 100644 --- a/src/task_state.rs +++ b/src/task_state.rs @@ -8,7 +8,7 @@ pub enum TaskState Starting, /// The state that each Task is in while it is actually - /// being process and running on a thread. + /// being processed and running on a thread. /// /// The PROCESSING state can only lead to WAITING, /// FINISHED, or UNKNOWN states. diff --git a/src/thread_state.rs b/src/thread_state.rs index 36e0607..a520522 100644 --- a/src/thread_state.rs +++ b/src/thread_state.rs @@ -1,17 +1,29 @@ -/// +/// The different states a Thread can go through during its lifetime. #[derive(Clone, Copy)] pub enum ThreadState { + /// The state that every Thread starts in. /// + /// The STARTING state can only lead to the IDLE state. Starting, + /// The state that the Thread is in when not processing. + /// During this state the Thread will be looking for new tasks + /// to work on, or if the Thread needs to be shutdown. /// + /// The IDLE state can only lead to the PROCESSING or FINISHED state. Idle, + /// The state a Thread is in when it is processing a Task. /// + /// The PROCESSING state can only lead to the IDLE or FINISHED state. Processing, + /// The state a Thread will be placed in when it is FINISHED running + /// and is ready to be destroyed. /// + /// The FINISHED state cannot lead to any states and shows that the + /// Thread is shutdown and ready to be destroyed. Finished }