Obsidian is a simulated OS written in ruby that supports process and resource managemen. It's easy to write your own tasks and scheduling algorithms
In case of not having ruby installed in your system refer to ruby install.
Clone this repository:
git clone https://github.com/pablo-co/obsidian
And then execute:
$ bin/setup
Obsidian comes bundled with a CLI. To run this CLI:
Assuming you are on the root of the project
bin/console
A prompt should be shown.
obsidian >> |
You can run many commands on the CLI with the following format: command argument1 argument2 .... To see all valid commands and their usage run help.
obsidian >> help
Usage: command argument1 argument2 ...
Options:
help Display this message
load_task_from_file [file] Load a task from a given YAML file
load_task_from_std_in Load a task from standard input
load_module [file] Load a Ruby file into memory
remove_task [pid] Remove a task from the ready queue
get_task_stats [pid] List all information of a task
set_scheduler [scheduler class] Sets the scheduling algorithm
set_running_time [time] Set Q in for scheduling policies
set_output_delay [delay] Set a delay for writing to the output device
set_automatic_scheduling [true|false] Schedule jobs automatically
step Run the scheduler and dispatcher once
steps [times] Run the scheduler and dispatcher n times
queues Prints the contents of all queues
set_memory_strategy [strategy class] Sets the memory strategy algorithm
process_memory_trace [input] [output] Processes a memory trace and outputs the result to a file
Bug reports, suggestions, updates:
https://github.com/pablo-co/obsidian/issues
You can load tasks from a file and from standard input. In both cases the user defined attributes are:
- priority: The task scheduling priority, it's importance depends on the scheduling algorithm.
- task: The file with the code that will be executed.
Loading a task from a file
obsidian >> load_task_from_file example_file.yml
The file format is exclusively YAML. The keys in the file are the task attributes while it's values are well... it's values.
Example file:
priority: 1
task: examples/sum.rb
Loading a task from standard input
Example user input:
obsidian >> load_task_from_std_in
priority: 1
task: examples/sum.rb
You can remove a task by specifying it's pid. Note: For consistency purposes you can only remove tasks that are in the ready queue.
obsidian >> remove_task [pid]
You can print all the attributes for a given task to the console.
obsidian >> get_task_stats [pid]
You can print all the scheduling queues with their corresponding tasks.
obsidian >> queues
You can change and even write your own scheduling algorithm. To change the algorithm you need to specify the class of this algorithm.
The built-in classes are:
- Obsidian::RoundRobinScheduler (Default)
- Obsidian::SJFScheduler (Schedules according to estimated burst time)
- Obsidian::PrioritySJFScheduler (Schedules according to priority)
obsidian >> set_scheduler Obsidian::SJFScheduler
To write your own algorithm see Scheduler
You can change the maximum time for which a task can run (the default is 10). To remove the burst time limit write infinity, this will effectively make all scheduling non-preemptive.
To set Q to 10 milliseconds.
obsidian >> set_running_time 10
Remove the maximum burst time. Make all schedulers non-preemptive.
obsidian >> set_running_time infinity
To write to the standard output all programs need to call sys.out which will write to stdout. This system call takes the task out of the running state and into the waiting queue. The delay is the amount of simulated time it takes to write to this device (the default is 1000).
obsidian >> set_output_delay 1000
You can change whether Obsidian should automatically schedule and dispatch a task or have the user do it manually (by defaults it's true).
To enable it.
obsidian >> set_automatic_scheduling true
To disabled it.
obsidian >> set_automatic_scheduling false
You can also run the scheduler and dispatcher manually. But first you have to disable automatic scheduling.
First make sure you disable automatic scheduling.
obsidian >> set_automatic_scheduling false
Run the scheduler and dispatcher once
obsidian >> step
Run the scheduler and dispatcher n times.
obsidian >> steps n
You can change the memory management strategy used when processing memory traces.
obsidian >> set_memory_strategy Obisidian::Memory::FirstFitStrategy
There are 3 built-in strategies:
- Obsidian::Memory::FirstFitStrategy
- Obsidian::Memory::BestFitStrategy
- Obsidian::Memory::WorstFitStrategy
To write your own strategy all you have to do is write a class that is a
subclass of Obsidian::Memory::Strategy and that implements
next_space_available. See any of the built-in strategies for reference.
You first have to load your custom strategy to memory:
obsidian >> load_module your_custom_strategy.rb
And then you just set it as the current memory strategy:
obsidian >> set_memory_strategy YourCustomStrategy
You can simulate the memory management process with a memory trace file. This file has the following format:
size_of_memory
number_of_available_spaces
starting_address_1, available_space_1
starting_address_2, available_space_2
...
starting_address_N, available_space_N
number_of_processes
pid, arrival_time, duration, size_of_memory
pid, arrival_time, duration, size_of_memory
...
pid, arrival_time, duration, size_of_memory
See examples/memory_trace.txt for an example memory trace.
To simulate the memory trace:
obsidian >> process_memory_trace examples/memory_trace.txt output.txt
This will parse the memory trace in the first file and output the result of doing memory management with the tasks and memory state given to the output file.
The output given by the example command:
Algorithm: FirstFitStrategy
Assigned processes: 1, 200, 115; 2, 600, 500; 3, 1100, 358; 4, 1458, 200; 5, 1658, 375
Blocked processes:
Memory utilization: 1548 / 4000 = 38.7%
Blocking probability: 5 / 0 = 0.0%
You can run almost any type of ruby code in Obsidian. This code runs in a sandbox thus has some limitations regarding system calls in general. This means you can't make use of files, threads and any other type of operation that interfaces with the operating system.
The only system call currently supported by Obsidian is writing to stdout.
sys.out 'Hello world!'The are several examples of programs in the examples folder.
You can load the example programs through the CLI to see them in action.
Currently the example programs are:
- examples/calculate_pi.yml
- examples/sum.yml
- examples/exception.yml
obsidian >> load_task_from_file examples/calculate_pi.yml
obsidian >>
[Output (0)]: PI ~= 4.0
[Output (0)]: PI ~= 2.666666666666667
[Output (0)]: PI ~= 3.466666666666667
[Output (0)]: PI ~= 2.8952380952380956
[Output (0)]: PI ~= 3.3396825396825403
obsidian >> set_scheduler Obsidian::RoundRobinScheduler
obsidian >> set_running_time 20
obsidian >> queues
Waiting:
Ready:
Running:
obsidian >> load_task_from_file examples/sum.yml
obsidian >> queues
Waiting:
Ready: (0 | 1 | 220.64876556396484 | 2016-03-30 21:30:37 -0600)
Running:
obsidian >> load_task_from_file examples/calculate_pi.yml
obsidian >>
[Output (1)]: Estimating the value of PI...
[Output (1)]: PI ~= 4.0
obsidian >> queues
Waiting: (1 | 2 | 6.8798065185546875 | 2016-03-30 21:30:42 -0600)
Ready:
Running: (0 | 1 | 1151.9584655761719 | 2016-03-30 21:30:37 -0600)
obsidian >>
[Output (1)]: PI ~= 2.666666666666667
[Output (1)]: PI ~= 3.466666666666667
[Output (1)]: PI ~= 2.8952380952380956
[Output (1)]: PI ~= 3.3396825396825403
obsidian >> remove_task 0
obsidian >> queues
Waiting: (1 | 2 | 6.8798065185546875 | 2016-03-30 21:30:42 -0600)
Ready:
Running:
All documentation is available online at RubyDoc
After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.
Bug reports and pull requests are welcome on GitHub at https://github.com/pablo-co/obsidian. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
The gem is available as open source under the terms of the MIT License.