I3ISU - Exercise 8: OS API

Introduction
The purpose of this exercise is to implement the missing pieces in a provided OO OS API.

Subexercise 1: Completing the Linux skeleton of the OO OS Api
The following files are missing or have not been completed.
 * inc/osapi/linux/Mutex.hpp - Missing
 * linux/Mutex.cpp - Missing
 * linux/Conditional.cpp - Already started
 * linux/Utility.cpp - Missing
 * linux/Thread.cpp - Already started
 * linux/ThreadFunctor.cpp - Already started

Implementation of the missing files
Testing the implementations of the missing files was done using the unit testing framework CppUTest. The tests are quick and dirty tests showing the interfaces of the OS API. I3ISU - Exericse 8: OS API (CppUTest)

Questions and answers

 * Inspecting the OSApi library, describe the chosen setup and how it works. Hint: Directory structure, define usage, handling platforms etc.

The directory tree for the source directory(src) looks like this: . ├── build │    └── lib │        └── host │            ├── debug │            └── release ├── common ├── example ├── inc │    └── osapi │        ├── details │        ├── example │        ├── linux │        └── win32 │            └── details ├── lib │    └── host │        ├── debug │        └── release ├── linux ├── test ├── util └── win32 └── details All the header files can be found in the inc directory and its subdirectories. The application utilizing the OS API should include header files from the inc directory. When a header has platform specific requirements, the header file in the inc folder refers the caller to the specific header in the plaform subdirectory. The cpp files containing code regarding specific systems can be found in directories linux and win32, while code that isnt system specific can be found in the common dir.


 * A thread function is a free C function, how is the connection made such that our desired run method is called.

The "Thread" class in the OS API takes an object inherited from the "ThreadFunctor" class in it's constructor. The "ThreadFunctor" class has a private method "void* threadMapper(void* thread)", which is the type of function "pthread_create" will accept as the function to run. "ThreadFunctor" passes a pointer to itself to "threadMapper" as a void pointer. This means that "threadMapper" has access to all members of the object inherited from "ThreadFunctor". A class inherited from "ThreadFunctor" implements the virtual method "run", which is called by "threadMapper".


 * In the windows implementation the so-called pimpl/cheshire cat idiom is used. Explain how it is used and what is achieved in this particular situation. Hint: The usage RAII<> seems to obfuscate what happens, but it is just a wrapper that delegates method calls to the object it contains. Check what happens in its structor.

Its for making it easier on compile and make time, its basically incomplete objects. As far as we can see it is used in f.x. the conditional that uses the conditionaldetails or something like that.


 * Why is the class Conditional a friend to class Mutex? What does it mean to be a friend? Hint: See the interface for class Mutex as coded for the windows platform.

Conditional is friend to Mutex to able to access its private members (the mutex variable), this way it stays private. See also http://en.wikipedia.org/wiki/Friend_class

Subexercise 2: On target
It has been verified that the OSApi library compiles for both Linux host and target. Unfortunately there was som problems porting the tests with CppUTest to the target. Testing that the OSApi works on both host and target is therefore left to subexercise 3, where the PLCS is implemented using the OS API.

Questions and answers
No changes to the code was needed.
 * Did you do need to change code for this to work, if so what?

Subexercise 3: PLCS now the OS Api
The purpose of subexercise 3 is to port the PLCS from I3ISU_-_Exercise_7:_Thread_Communication#Subexercise_3:_Enhancing_the_PCLS_with_Message_Queuesso that is based on the newly created OSApi. UML diagrams should be used to depict the design. The basic design of the new PLCS is equal to the one described in I3ISU_-_Exercise_7:_Thread_Communication#Subexercise_3:_Enhancing_the_PCLS_with_Message_Queues(See the State Diagram). The only difference is the implementation using the new OS API. The use of the OS API is shown in the following class diagram:

Running the program on host
Running the code on host gives the following: Car - ID=2: Car is in queue for Entry Car - ID=0: Car is in queue for Entry waiting for Entry authorization Entry Guard: Gate opened Pass Authorization sent to CAR, ID=2 Car - ID=1: Car is in queue for Entry Car - ID=2: waiting for Entry authorization Entry Guard: Pass Authorization sent to CAR, ID=0 Car - ID=1: waiting for Entry authorization Car - ID=2: Car entered PL               Car is Parked Car - ID=0: Car entered PL               Car is Parked Entry Guard: Pass Authorization sent to CAR, ID=1 Car - ID=1: Car entered PL               Car is Parked Entry Guard: Car with ID: 2 passed gate Car with ID: 0 passed gate Car with ID: 1 passed gate Gate is closed Car - ID=2: Car is in queue for Exit waiting for Exit authorization Car - ID=1: Car is in queue for Exit Exit Guard: Gate opened Car - ID=1: waiting for Exit authorization Car - ID=0: Car is in queue for Exit waiting for Exit authorization Exit Guard: Pass Authorization sent to CAR, ID=2 Pass Authorization sent to CAR, ID=1 Car - ID=2: Car exited PL Entry Guard: Car with ID: 2 passed gate Exit Guard: Pass Authorization sent to CAR, ID=0 Car - ID=0: Car exited PL              CRUISING THE REAL WORLD Car - ID=1: Car exited PL              CRUISING THE REAL WORLD Car - ID=2: CRUISING THE REAL WORLD Entry Guard: Car with ID: 1 passed gate Car with ID: 0 passed gate

Running the program on target
(The output shown here from the target is from a version that contained a mistake sending messages to the entry queue which should have been sent to the exit queue) Running the code on target gives the following: root@beagleboard:~# ./PLCS_prog Car - ID=0: Car is in queue for Entry waiting for Entry authorization Entry Guard: Gate opened Pass Authorization sent to CAR, ID=0 Car - ID=0: Car entered PL 	Car is Parked Entry Guard: Car with ID: 0 passed gate Gate is closed Car - ID=1: Car is in queue for Entry waiting for Entry authorization Entry Guard: Gate opened Pass Authorization sent to CAR, ID=1 Car - ID=1: Car entered PL 	Car is Parked Entry Guard: Car with ID: 1 passed gate Gate is closed Car - ID=2: Car is in queue for Entry waiting for Entry authorization Entry Guard: Gate opened Pass Authorization sent to CAR, ID=2 Car - ID=2: Car entered PL 	Car is Parked Entry Guard: Car with ID: 2 passed gate Gate is closed Car - ID=0: Car is in queue for Exit waiting for Exit authorization Exit Guard: Gate opened Pass Authorization sent to CAR, ID=0 Car - ID=0: Car exited PL 	CRUISING THE REAL WORLD Entry Guard: Car with ID: 0 passed gate Car - ID=1: Car is in queue for Exit waiting for Exit authorization Exit Guard: Pass Authorization sent to CAR, ID=1 Car - ID=1: Car exited PL 	CRUISING THE REAL WORLD Entry Guard: Car with ID: 1 passed gate Car - ID=2: Car is in queue for Exit waiting for Exit authorization Exit Guard: Pass Authorization sent to CAR, ID=2 Car - ID=2: Car exited PL 	CRUISING THE REAL WORLD

Questions and answers
There was not made any major design changes. The implementation is different though when utilizing the OSApi. Thread functions are now implemented creating a class inheriting from "ThreadFunctor" which implements the method "run". No. It only makes it easier to port to some other platform since the OSApi is just some generic interface.
 * Which changes did you make and why?
 * Does this modification whereby you utilize the OSApi library improve your program or not. Substantiate you answer with reasoning.