techmanual.txt

***Solar OS 1.3.0***

Technical Support Manual
---------------------------
Table of Contents:
	I. Table of Contents.
	II. Overview
	III. Structure,Classes,Functions,Data Structures
	IV - Cross References
	V - Index
--------------------------------------
II. Overview :
	The interface was built using the command design pattern.
	This allows additional functionality to be added in the future easily.
	To implement this design patterns, a class for each concreteCommand was needed.
	These concreteCommands inherit from a abstract base class named Command.
	The ABC class has one method, execute, the concrete commands override this method.
	The actual implementation of the commands are not in the concrete command execute method.
	The actual implemntation of the commands are in the receiver class. 
	The receiver class is decoupled, it does not know about any other class.
	The concrete command execute method therefore calls receiver->(command).
	However, the concrete command execute method is not called directly.
	There is a class called the invoker that must call the concrete command's execute method via invoker->execute(command)
---------------------------------------
III. Program Structure/Fuction Description:
	UML diagram - http://www.dofactory.com/images/diagrams/net/command.gif
	
	main: does the following:
		creates a client object.
		displays a welcome message via a void function
		calls client.osLoop(input) on user input to run the OS.
	client:
		public members:

		contains public vectors for each concrete command
		versionVec,dateVec,directoryVec,historyVec,batchVec,
		aliasingVec,exitVec,helpVec
		Also contains commandVecs which contains all 
		present commands on the system including aliases
		This vector is necessary for userInput to be accurate so that 
		alias command calls work.

		private members:
		contains a pointer for receiver,invoker, and all concrete commands
		
		functions:
			void osLoop(string input):
			the main operating system loop, checks for user input
			and if input matches a command, 
			calls invoker->execute(0-7)
			the parameter 0-7 depends on the command to be executed
			these are initialized in slots on the constructor

		constructor:
		sets the concrete commands into their proper slots:
		invoker->setCommand(0, version);
    		invoker->setCommand(1, date);
    		invoker->setCommand(2, directory);
    		invoker->setCommand(3, history);
    		invoker->setCommand(4, batch);
    		invoker->setCommand(5, aliasing);
    		invoker->setCommand(6, exit);
    		invoker->setCommand(7, help);
    		
		batch and aliasing:
		batch and aliasing are implemented into the client 
		unlike the other commands, they could not be implemented
		in the receiver class because the receiver class is 
		decoupled and isn’t aware of any other class 
		so it couldn’t access the proper class members
		to implement aliasing or batch in the receiver class.
		These are not contained in functions.
		
		aliasing:
			asks the user for their new command nickname
			makes sure input is currently not already
			a mapped command by using the algorithm
			find method and iterating through commandVecs
			asks user for the command they want to rename
			makes sure that the command exists by using
			the algorithm find method and iterating
			through commandvecs.

		batch: asks user for the input file name
			makes sure file is valid, returns error if not
			if found, executes the commands in the script
		

		client summary:

		constructor sets concrete commands in appropriate slots.
		osLoop is what powers the OS interface it takes a string input
		and is called from main when the program begins.
		osLoop iterates through each concreteCommand vector 
		checking for valid concreteCommands as well as their aliases.
		the [0] index of each vector will always be the original
		concrete command and any additional vector elements
		are aliases. When a valid command is entered,
		invoker->execute(0-7) is called depending on what command
		was entered. The invoker executes this command which calls
		the concreteCommands execute method which calls 
		receiver->command() where command is equal to whichever
		command was called in the client and that command’s function is 			successfully executed since that is where the command’s implementation
		is held.
	
	invoker:
		public members:
		
		contains std::vector<Commands*>commandvec
		this vector holds the concrete commands
		
		functions:
		void setCommand(int slot, Commands *command);
			this function is responsible for setting
			the concrete commands in their appropriate
			slots.
		void execute(int slot);
			this function is responsible for
			calling the concrete commands execute method
			by calling commandvec[slot]->execute();

		constructor:
			calls commandvec.reserve(numHere);, 
			where numHere = num of commands on system, The client initializes
			the commands in their proper slots.

		invoker summary:
			reserves appropriate number of slots for the appropriate # of concrete commands
			in its member vector
			invoker provides a method for the client
			to initialize all the commands in their
			proper slots. also important: invoker
			calls the concreteCommands execute method
	receiver:
		public members:
		receiver holds all the functions for
		command implementation.
		There is one function for each command:
		version,date,directory,history,batch,aliasing
		exit,help,createPCB,deletePCB,block,unblock,showPCB,showAll,showReady,showBlocked,generateRandomPCBs,exec

		pcb *cpu;
               std::deque <pcb> ready;
               std::deque <pcb> blocked;
               std::deque <ioEvent> eventQueue;
               int maxMemory;
		struct memorySystem
    		{
        		pcb pcb;
        		int memory;
        		bool inUse = false;
    		};
		std::list<memorySystem> memLinkedList;
		
		private members:
		std::vector<std::string> commandhistory;
			this vector is needed to implement the 
			history command. Each time a command is executed
			a string of the commandName is pushed into
			this vector.

		functions:
			note: All functions push a string of the name
			of the command executed to the commandhistory vec
		void receiver::version()
			simply prints the version to the screen
		
		int receiver::exit()
			exits the program
		void receiver::date()
			prints the date to the screen using the
			underlying OSX date command
		
		void receiver::directory()
			prints the directory to the screen using
			the underlying OSX ls command

		void::receiver::history()
			prints a history of commands used during
			the shell session. by iterating through the
			commandhistory vet and printing to the screen.

		void receiver::aliasing()
			only pushes the string “aliasing” to the
			commandhistory vec. the aliasing technique
			 is implemented in the client class

		void receiver::help()
			prints out a list of the commands and
			what they do.

		void receiver::batch()
			only pushes the string “batch” to the
			commandhistory vec. the batch technique
			 is implemented in the client class

		void receiver::createPCB(int id, int memory);
                              asks user for an ID and memory
                              creates a PCB and sends it into the readyQueue.
                              checks and makes sure ID is unique and memory < maxMemory


    		void receiver::deletePCB(int id);
				asks user for an ID.
				searches for ID in both ready queue and blocked queue
				if process is found it is deleted, if not, returns error.


    		void receiver::block(int id);
				asks user for an ID.
				searches for ID in ready queue.
				if ID is found, process is removed from ready queue.
				process is inserted into blocked queue.


    		void receiver::unblock(int id);
				asks user for an ID.
				searches for ID in blocked queue.
				if ID is found, process is removed from blocked queue.
				process is inserted into ready queue.
				

    		void receiver::showPCB(int id);
				asks user for an ID.
				displays all attributes of that process. (all member variables of a pcb object)


    		void receiver::showAll();
				displays all attributes of every process in any queue in the system.
				
    		void receiver::showReady();
				displays all attributes of every process in the ready queue.

			
    		void receiver::showBlocked();
				displays all attributes of every process in the blocked queue.
				
    		void receiver::generateRandomPCBs();
				asks user for # of processes to generate.
				for each process, a random number for ID is generated (0-10000 now, can be changed)
				for each process, a random number for memory is generated (0-maxMemory)
				calls createPCB that # of times.


    		void receiver::exec();
				this is the execution function.
				creates a text file for execution trace and memory trace.
				asks user whether to bestFit,worstFit,nextFit, or firstFit.
				sets cpu = to the front of the ready queue.
				simulates processing time by setting cpuUsage to rand (0-10000);
				adds that # to cpuUsageTerm.
				updates all other processes in the readyQueue by adding that to waitingTerm.
				exec decides what to do with a process based on a random number generator.
				every cycle its possible for a process to be terminated
				blocked waiting for an userioevent
				blocked waiting for an hardwareevyent
				sent back to ready queue.
				if a process is ever blocked, its iorequexstterm is updated every cycle.
				every 10th cycle possible for an userIO or hardwareIO event to be generated
					

    		void receiver::setMaxMemory();
				User enters an integer to set max memory
				Currently autocalled at runtime and shouldn’t be called dynamically.


		receiver summary:
			Contains the actual command implementation code
			when a concreteCommands execute method is called
			e.g.(receiver->(version) (by invoker) the
			proper command method in receiver is executed
			is not aware of any other classes.
			when a cmd method in receiver is called a string of
			the command name is pushed into receiver’s
			vector commandHistory which is iterated
			through in the receiver::history method.

			

	Command:
		this is an abstract base class
		functions:
			virtual void execute = 0();
				All the concrete commands inherit
				and overwrite this method with a call
				to receiver->command() where command
				is equal to the command name.
		Command summary: 
			The abstract base class that
			all concrete commands inherit.
			The concrete commands override the
			virtual void execute = 0 method in
			Command.
				

	The commands:
		There is one class for each command.
		All commands inherit the Command ABC class.

		private members:
			receiver *receiver;
			Each command has a receiver ptr as a data member
			
		functions:
			virtual void execute();
			Each command has this, which is derived
			from the ABC class. Each command
			calls receiver->command() here. where command 
			is equal to whatever the command name is.

		The commands summary:
			One class for each command, all designed
			exactly the same since the actual
			command implementation is in receiver.
			Their execute method calls 
			receiver->command(); where command is the
			name of the command class.
			e.g. version would be receiver->version();
			Note: the concreteCommand classes execute
			method is called from the invoker.

	pcb:
		The pcb class represents a pcb. has member variables:
			PID,cpuUsageTerm,ioRequestTerm,waitingTerm,memory,
			eventRequested,sentToBlock
	ioEvent - the ioEvent class represents an ioEvent. has member variables:
		   eventType and time. eventType 2 is a userIOevent, type 3 is a hardware.
		   time represents what time cycle the event happened.
			
————————————————————————————————————		
IV. Cross References -
	
	(functions calling functions):

	1. Each concrete commands execute method calls its respective
	command method in the receiver class. 
	For example:
	void version execute()
	{
		receiver->version();
	};

	2. invoker:
	the invoker::execute(int slot) function calls
	the respective concreteCommand’s execute function.
	
	3. client::osLoop(std::string input)
		The client osLoop calls the invoker’s execute
		method with a proper command slot number as a parameter
		This slot number depends on what command the user
		enters. One such call is invoker->execute(0);

	   For “batch” input, osLoop also calls itself so that
           it can process the batch script.

       4. void receiver::generateRandomPCBs();
		calls createPCB x many times, where x how many PCBs the user wants to generate.
	5. void receiver::exec();
		calls deletePCB() when rng decides to delete the current process in the cpu.
		calls block when rng decides to block a process.

——————————————————————
V. Index -
	I. Table of Contents.
	II. Overview
	III. Structure,Classes,Functions,Data Structures
	IV - Cross References
	V - Index
—————————————————