CSE 532 Fall 2015


Lab 0: "All the platform's a stage, and all the threads merely players"

Points: 5% of final grade

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

Due: by 11:59pm Tuesday September 15, 2015


Purpose

The purpose of this assignment is to give you experience with multi-threaded programming and basic synchronization techniques, using C++11 threading and synchronization features. We will use wrapper facades from the C++11 libraries, and the design, implementation, testing, and debugging skills you'll develop using them, repeatedly throughout the semester.


Assignment

In this assignment you will work in groups of 1, 2, or 3 people (but not more) to write a C++11 program (in Visual Studio 2013) that can:
  1. launch multiple threads that read individual parts of a fragment of a play from separate input files;
  2. synchronize the transfer of lines from those parts into a common script; and
  3. sort the lines and print out the order in which they would be given in the play.
You will start by writing a simple program in which the main thread of execution will:
  1. read a configuration file giving the the name of the play (or fragment of a play) and the names of the characters and the files where their parts are defined;

  2. construct a Play object through which lines of the play will be stored, sorted, and printed out;

  3. launch threads that each will (asynchronously) read their part from their individual files and insert them into the Play obect;

  4. join with each of the threads; and then

  5. print out a properly ordered script for the entire fragment of the play.

Throughout this assignment, you will work with input files in particular formats (which different parts of the program you are writing will use as described above). For example, based on a portion of William Shakespeare's "Hamlet, Prince of Denmark", ACT II, Scene II, "A room in the Castle." (text obtained from the Literature Page web site at http://www.literaturepage.com/read/shakespeare_hamlet-31.html) the script fragment hamlet_act_ii_scene_2.txt can be represented by the configuration file hamlet_ii_2_config.txt and the corresponding part files Guildenstern.txt, King.txt, Queen.txt, and Rosencrantz.txt. To complete this assignment please perform the following tasks:

Play Class


Extra Credit

For up to an extra 5 percent of the assignment's value (scores of up to 105 are possible) write a separate program that can take (1) the name of a script fragment file (in the format illustrated by the hamlet_act_ii_scene_2.txt script fragment file) to process, (2) the name of a configuration file to generate, and (3) the name of the play (given in the remaining command line arguments); and can output an appropriate configuration file (for example like hamlet_ii_2_config.txt) and the part files corresponding to the configuration file and the ordering of lines in the script fragment file (like Guildenstern.txt, King.txt, Queen.txt, and Rosencrantz.txt).

Submit your solution to the extra credit part in a separate .zip file (clearly named to indicate it's the extra credit part) that you should attach along with the other parts of the assignment to the e-mail you send when submitting your solution. Also write up your approach to the extra credit part, give instructions for how to unpack, build, and use it, and document how you used it in your testing of the assignment, in the main ReadMe.txt file for your assignment (instead of creating a separate ReadMe.txt file for the extra credit part).


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.

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

  1. the number of the lab (e.g., "CSE 532 Fall 2015 Lab 0")
  2. the names and e-mail addresses of all team members
  3. an overview of how your programs are designed,
  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 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: