Milestone 4

Assigned:	11/6
Due:	Wednesday 12/5 by 11:59 pm

Updates

Mon Nov 12 09:27:01 EST 2018: split the last task up to better guide your development. Added an example code for handling OS signals.

Introduction

In this last milestone you will develop the final version of the application using separate threads for the GUI and interpreter kernel. You must have completed at least milestone 0 and 1 and the basic GUI portion of Milestone 2 before attempting this one.

Note: Your final project grade will be evaluated using your Milestone 4 submission. All current and previously specified functionality should be available. See the project overview page for the final project grading criteria.

Background Information

Task 0: Update CMakeLists.txt

You will need to make the following change to the CMakeLists.txt file to allow the threaded version on plotscript and unit_tests to compile in the reference environment and the grader. Just add the pthread library to the target_link_libraries as shown in the diff below.

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 5f0c883..6e1172c 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -111,8 +111,8 @@ if(DEFINED ENV{ECE3574_REFERENCE_ENV})
   set(GCC_COVERAGE_COMPILE_FLAGS "-g -O0 -fprofile-arcs -ftest-coverage")
   set_target_properties(interpreter PROPERTIES COMPILE_FLAGS ${GCC_COVERAGE_COMPILE_FLAGS} )
   set_target_properties(unit_tests PROPERTIES COMPILE_FLAGS ${GCC_COVERAGE_COMPILE_FLAGS} )
-  target_link_libraries(unit_tests interpreter gcov)
-  target_link_libraries(plotscript interpreter gcov)
+  target_link_libraries(unit_tests interpreter pthread gcov)
+  target_link_libraries(plotscript interpreter pthread gcov)
   add_custom_target(coverage
     COMMAND ${CMAKE_COMMAND} -E env "ROOT=${CMAKE_CURRENT_SOURCE_DIR}"
     ${CMAKE_CURRENT_SOURCE_DIR}/scripts/coverage.sh)

Task 1: Message queues for input strings and expressions

Using one or more classes and the standard C++11 threading library, implement the functionality to pass a string containing a plotscript program and an arbitrary Expression between threads in a safe manner. Be sure to unit test your module(s) fully before moving to the remaining tasks. Add any files you create to the CMakeLists.txt file in the appropriate place.

Task 2: Move interpreter kernel to separate thread

Redesign your code so that the parsing and evaluation of plotscript happens in a separate thread from that of the main program, TUI (plotscript) or GUI (notebook). The thread should be started upon program creation and be stopped before program exit. This should use the modules from task 1 to send the input string to the interpreter thread and receive the result for display asynchronously (that is do not just use std::async). You must use C++11 threading in both programs and neither the unit tests or plotscript program can link with Qt. Be sure to add any files you create to the CMakeLists.txt file in the appropriate place.

You should write extensive unit tests to ensure your threaded interpreter kernel works correctly before moving to task 3. Note that you should use Catch's CHECK assertion rather than REQUIRE between starting and stopping of threads. otherwise your unit tests will abort abnormally on test failure.

Task 3: Starting and stopping the interpreter kernel

Add the ability to control the interpreter kernel thread as follows.

In the TUI (plotscript), when in REPL mode (only), this functionality should be controlled using special (non-plotscript) commands:

typing %start and pressing enter should start an interpreter kernel is a separate thread. It should have no effect if a thread is already running. The number of threads used should be two after this command.
typing %stop and pressing enter should stop a running interpreter kernel. It should have no effect if a thread is already stopped. The number of threads used should be one after this command.
typing %reset and pressing enter should stop and reset a running interpreter kernel to the default state, clearing the environment. It should then start a new running kernel. The number of threads used should be two after this command.

If a user enters a plotscript expression when the interpreter is not running, display the error message: "Error: interpreter kernel not running".

In the GUI (notebook_app) add QPushButtons to start/stop/reset the kernel with the same functionality of the corresponding TUI commands should be added in a layout at the top of the NotebookApp Widget (see figure). These should have the objects names "start", "stop", and "reset" respectively.

In the GUI, if a user enters a plotscript expression for evaluation (using shift-enter) when the interpreter is not running, display the error message (using the OutputWidget): "Error: interpreter kernel not running". Otherwise, disable the InputWidget until the result is ready to be displayed, at which time the result should be displayed in the OutputWidget and the InputWidget re-enabled.

Task 4: Interrupting the interpreter kernel

Add the ability to interrupt the evaluation of plotscript expressions.

In the TUI, typing %exit and pressing enter should exit the plotscript REPL with EXIT_SUCCESS. Be sure to stop any running threads before program exit.
In the TUI, typing Cntl-C (holding down the Control key and pressing the C key) should interrupt a running interpreter kernel evaluation as soon as possible. That is it should be possible to interrupt the interpreter during evaluation. Plotscript should immediately display the error message: "Error: interpreter kernel interrupted", be left running, and any environment changes prior to the interruption discarded. It should have no effect if a thread is stopped. An example program demonstrating how to handle signals like Cntl-C is here.
In the GUI (notebook_app) add another QPushButton to interrupt the kernel with the same functionality of Cntl-C in the TUI, except the message is displayed in the OutputWidget. This button should have the object name "interrupt".

Submission

To submit your milestone:

Tag the git commit that you wish to be considered for grading as "milestone4".
```
git tag milestone4
```
Push this change to GitHub
```
git push origin milestone4
```

If you need to tag a different version of your code simply create and push a new tag appending a monotonically increasing number to milestone4 using '-', e.g. milestone4-2, milestone4-3, etc.

Be sure you have committed all the changes you intend to. You should re-clone your repository into a separate directory and double check it is what you intend to submit. Failure to complete these steps by the due date may result in a failed submission.

Grading

There are 6 course percentage points allocated to this milestone. You will receive a detailed feedback report on your submission via Canvas before the end of final exams.

Code compiles in the reference environment	0.5 points
Correctness Tests	4 points
Testing	0.5 points
Code Quality	0.5 point
Good Development Practices	0.5 point

Grading Notes:

If your code does not build in the reference environment you will receive no points.
Correctness can be checked in the auto-grader and is determined by the proportion of instructor tests that pass.
Testing includes both unit test coverage and completeness of NotebookApp functional tests. Unit test coverage can be determined in the reference environment using the same procedure in Milestone 1.
Code quality means your code compiles with no warnings at a high-warning level (STRICT in the reference environment) and your unit tests have no memory leaks, as well as other criteria mentioned in class (function length, variable naming, etc).
Good development practices is assessed by looking for regular, incremental, and well-packaged commits.