CSE 532 Fall 2015


Lab 2: "One thread in its time plays many parts"

Points: 15% of final grade

Submitted: by electronic submission to cse532@seas.wustl.edu

Due: by 11:59pm Sunday November 1, 2015 (please note new deadline)


Purpose

The purpose of this assignment is to expand your experience with multi-threaded programming and synchronization techniques, using additional C++11 threading and synchronization features including techniques for managing thread pools. We will use wrapper facades from the C++11 libraries, and the design, implementation, testing, and debugging skills you'll develop using them, in the semester's final project as well.


Assignment

In this assignment you will work in groups of 1, 2, or 3 people (but not more) to evolve (again in Visual Studio 2013) the C++11 program you wrote for lab 1 to:

If you are working in a different team for this lab than in a previous lab, you are allowed to reuse code from any of your earlier lab solutions though if you do that you should please add comments acknowledging contributions from anyone who is not on your current team (and noting in which previous lab their contributions were made), to the code you submit.

Make separate copies of the (source and header) code files from lab 1 that you are using for this assignment, and put them into the directory where your new project keeps its own source files, before adding them to your lab 2 project. Not only can this (1) avoid confusing Visual Studio (with regard to which files to build, where to find the object files from them, etc.), but it also makes it easier to ensure (2) you have all the files when packaging up your solution to submit it, and makes it easier (3) to revert to a previously stable code base if a change you are trying doesn't pan out well.

In this assignment, you will again work with input files in similar formats as in the previous lab 1 assignment, but instead of working with a single configuration file will work with a script file that contains the names of a sequence of configuration files, each of which defines a scene fragment as in the previous labs.

For example, the first part of Act II from William Shakespeare's "Hamlet, Prince of Denmark", (text obtained from the Literature Page web site at http://www.literaturepage.com/read/shakespeare_hamlet.html), can be represented within a script file (partial_hamlet_act_ii_script.txt) that contains an ordered sequence of [scene] directives, each of which is followed by the name(s) of one or more configuration files (hamlet_ii_1a_config.txt, hamlet_ii_1b_config.txt, and hamlet_ii_2a_config.txt) for scene fragments that in the play are delimited by character entrances and/or exits:

hamlet_act_ii_scene_1a.txt,
hamlet_act_ii_scene_1b.txt, and
hamlet_act_ii_scene_2a.txt

(we'll implement a simple version of character entrances and exits in this lab, and then will further extend this feature in lab 3).

As in the previous labs, each scene fragment's configuration file gives the name of each character in the scene fragment along with their corresponding part file (e.g., Polonius_hamlet_ii_1a.txt and Reynaldo_hamlet_ii_1a.txt in hamlet_ii_1a_config.txt, Polonius_hamlet_ii_1b.txt and Ophelia_hamlet_ii_1b.txt in hamlet_ii_1b_config.txt, and King_hamlet_ii_2a.txt and Queen_hamlet_ii_2a.txt and Rosencrantz_hamlet_ii_2a.txt and Guildenstern_hamlet_ii_2a.txt in hamlet_ii_2a_config.txt).

Note that for this lab the names of the scenes have moved from the individual configuration files into the script file's [scene] directives. To complete this assignment please perform the following tasks:

Play Class

Director Class

Player Class

Main Function


Extra Credit

For up to an extra 5 percent of the assignment's value (scores of up to 105 are possible) complete one or both of the following optional extra credit options.


What to Submit

ReadMe.txt

As you work on your program, please write down the design decisions you faced, and describe both the solutions you chose to address them and the rationale for the choices you made, in the ReadMe.txt text file that should have been generated by Visual Studio 2013. In this lab, the project report in your ReadMe.txt text file will be worth 10 percent of the grade (up from five percent in the previous labs, which will increase further to 20 percent of the grade on the final project).

The first section of your ReadMe.txt file should include:

  1. the number of the lab (e.g., "CSE 532 Fall 2015 Lab 2")
  2. the names and e-mail addresses of all team members
  3. an overview of how your programs are designed, including all the design discussions requested above,
  4. the Wrapper Facades you used or extended and how they helped in your design and code, and
  5. insights, observations and questions you encountered while completing the assignment.

The second section of your ReadMe.txt file should provide detailed instructions for how to:

  1. unzip or otherwise unpack your files,
  2. build your program(s), and
  3. run your program(s) on the Urbauer 218 lab machines where we will evaluate your lab solutions.
Important:We must be able to receive your e-mail, and unpack, build, and run your programs using only the instructions in your ReadMe.txt file and the Visual Studio 2013 version and other tools available on the CEC Windows lab machines in Urbauer 218.

The third section of your ReadMe.txt file should provide a reasonably detailed description of how you evaluated your solution, including the kinds of configuration and character part files you used and their formats (including well formed and badly formed content, misordered lines, etc. to test how your program handled those variations), and any other scenarios that you tested that you consider important.

Electronic Submission

Please submit by e-mail to cse532@seas.wustl.edu with a single .zip file attached containing:
  1. your source code and header files,
  2. any example files you think useful (for example, the different configuration and character part files you used to test your solution),
  3. output files from at least one significant test of your programs, and
  4. your ReadMe.txt file.

Please also send in a separate copy of your ReadMe.txt file, with clear instructions on how your submission file was produced and how to unpack it using tools available on the CEC lab machines. IMPORTANT:please make sure that no .exe file is included in any .zip file you send, as the WUSTL e-mail servers will block delivery of email with a .zip attachment that includes a .exe file. Please also make sure to send a .zip file (not a .7z file or other zip format) when you send your solutions.

Grading

Please treat this assignment as you would a commercial or research product that you are shipping to a large group of customers. Please take the time to test, document, and check your work to make sure all parts are shipped, are of high quality, and behave resonably under a range of different operating conditions. Grading will focus both on the quality of your solution and on the quality of the product itself, as it arrives at the cse532 account. To ensure the best possible result (and accordingly the highest possible grade), please pay attention to the following issues:

Correct Compilation and Operation

Your program must compile and run correctly on the CEC Windows lab machines using the source files you provide. Please make sure your program compiles without warnings (and of course without errors), and you might even want to try running it on different compilers (say also using g++ on shell.cec.wustl.edu or one of the other Linux servers) and fixing all the warnings for each. Missing files will be handled with a 5 point deduction (possibly per file) if you need to supply a new file in order for us to build your solution on the CEC Windows lab machines.

Design Quality

Design decisions are largely yours to make, and as long as the design is concise, coherent, consistent, and addresses all design forces in the assignment, you will receive full credit. One key area to consider is whether each abstraction in your design does a single job, does that job completely, and collaborates appropriately with other abstractions. Minor deductions (1-3 points, but please be aware minor deductions can add up) will be made for abstractions that are unnecessarily large or have inappropriate inter-dependencies. Major deductions (5-15 points) will be made for larger problems like neglecting key requirements of the assignment, code that does not compile or that crashes when it runs, etc.

Implementation Quality

How you implement your solution is again up to you, and we will take into account different approaches to implementation. Minor deductions will be made for things your program gets away with but are not good, like neglecting to check the return value from a system call or Wrapper Facade method (i.e., the program may have problems under special conditions), or calling exit(1) from inside a class method rather than providing a clean termination path. Major deductions will be made for problems that produce incorrect or extremely inefficient behavior of the program. The former kinds of errors should be eliminated during your coding and code review phases, and the latter kinds of errors should be eliminated during your testing phase, which should include running different combinations of configuration and character part files containing well formed and/or badly formed contents.

Coding Style

Different coding styles will also be accepted, as long as they are clear, readable, and consistent. Please code clearly with both the reader of the code and the user of the program in mind. Please use consistent indentation and placement of braces, and comment your code thoroughly. Use whitespace liberally - it's free and it makes it a lot easier to read your code. When grading, we will add tagged comments to the code indicating areas where we found particular issues to mention, whether or not points are deducted. Only minor deductions will be made for each style issue, except in extreme cases.

Documentation

Please make sure you provide adequate instructions on how to unpack, build, and run your program. Also, please make sure to document your solution. Minor or even major deductions will be made for inadequate explanation of how your solution does what it does, why you made key design choices, or how the user (or grader) can successfully build and run your program. Even if how you did something is obvious to you, please assume it is not obvious to the reader.

Missing Files

Missing files in the delivered software make it difficult or impossible to evaluate your solution. An automatic deduction of up to 5 points will be applied for each missing or corrupted file that is submitted later on request.

Late Submission

Labs recieved within 24 hours after the deadline will be graded with an automatic 10 point deduction. Labs received more than 24 hours after but within 48 hours of the deadline will be graded with an automatic 20 point deduction. Labs received after 48 hours from the deadline will not be graded, except under extenuating circumstances. If you are running late completing the assignment, please let us know about the trouble as soon as possible (and it may be possible to give you a brief extension if you request it sufficiently in advance of the deadline), and please turn in as much as you can before each deadline so we can give at least some credit for the work you have done.

Grading Issues from Previous Semesters

Please avoid the following practices, which have at least drawn at least comments (and possibly deductions depending on the extent of the issue) in previous semesters: Please use the following practices to improve the clarity and quality of your code and documentation:

Posted 11:15am Monday October 5, 2015 by Chris Gill.

Changes since original posting: