JMU
Programming Assignment 8


1 Summary

The (fictitious) company zmedia has done some usability testing of the free_bookz_player and have, as a result, written some new requirements. You have been hired to implement the changes.

2 Specifications and Other Documents

zmedia has provided you with the following documents.

3 Additional Specifications/Constraints

In addition to conforming to the documents provided by zmedia (and all related course policies), your code must satisfy the following additional specifications/constraints.
  1. The main() function of the free_bookz_player must call the display_all() function in the bookz_lib module directly. In other words, the bookz must be displayed in the main thread. (As in version 1.)
  2. The start_adz() function must be called in a "helper" thread. (As in version 1.)
  3. The threads must use shared variables to "communicate". (New in version 2.)
  4. The system must use pthread_mutex_t variables to coordinate access to the shared variables. (New in version 2.)
  5. The system may (but need not) use pthread_cond_t variables to notify threads of state changes. (New in version 2.)
  6. Both the bookz and the ads must be displayed on STDOUT_FILENO. (As in version 1.)
  7. Though the bookz_lib module may change, the bookz_player executable must build and execute exactly as it did before the introduction of the free_bookz_player.

4 Understanding the Requirements

4.1 Satisfying Requirement 1 of the SRS

Though there is no way for the users to know this, the issue they encountered arises because the lines of the bookz are displayed in the main thread and the text of the advertisments are displayed in the helper thread (and there is no coordination between the two).

Hence, in version 2, both the lines of the bookz and the text of the advertisments must be displayed in the main thread. Specifically, the line of the bookz must be displayed, the main thread must sleep for 1 second, and then the text of the advertisment must be displayed. Of course, this will mean that the display_all() function in the bookz_lib module must be modified so that it now calls the display_adz() function in the adz_lib module.

4.2 The New Role of the start_adz() Function

In version 1, the start_adz() function iteratively read information from the adz file and called the display_adz() function. Now the display_adz() function is called by the display_all() function, so the start_adz() function must play a different role.

In version 2, the start_adz() function (which still executes in the helper thread) must read from the adz file and assign values to one or more shared variables that the display_adz() function (which executes in the main thread) uses.

At a minimum, you must have a shared variable (named adz_current_text) that contains the text of the advertisment. (Was a variable with file scope in version 1.)

You may also want to have a shared variable (named adz_updated) that indicates whether or not adz_current_text has changed since it was displayed and a function named adz_is_updated() that can be used to check the value of this variable. You may, instead, want to use a pthread_cond_t variable for this purpose.

Of course, you must coordinate access to the shared variable(s) and/or pthread_cond_t variables using one or more pthread_mutex_t variables.

4.3 Satisfying Requirement 2 of the SRS

To satisfy this requirement you must use a shared variable (named bookz_done) that the start_adz() function will use (in the helper thread) to determine whether it should stop iterating. This variable will be set by the main thread (when the bookz is done).

Of course, you must coordinate access to this shared variable using one or more pthread_mutex_t variables.

4.4 Satisfying Specification/Constraint 7 Above

As discussed above, you will almost certainly need to add code to the bookz_lib module. However, for obvious reasons, it is important that the bookz_player continue to (build and) execute as it did before. This is best accomplished using preprocessor directives. The code (and other preprocessor directives) specific to the free_bookz_player should be added between #ifdef ADZ and #endif ADZ directives. Then, when building the free_bookz_player module, you should define the symbol ADZ (e.g., using the -D ADZ option or a #define ADZ directive). In this way, the code that is specific to the free_bookz_player will only be included in the free_bookz_player.

5 Design Help

You have been given specifications for the product but not a design of the modules. Hence, you will need to make some design decisions and there are several possible options. The two most obvious are discussed below.

5.1 A Design Motivated by OOP

Though C is not an object-oriented programming languages, you can still design modules that are motivated by object-oriented concepts. In the case of this assignment, that would mean using variables with file scope and internal linkage and using functions to modify and access those variables.

For example, if you use this design you will want to add a function (with external linkage) to the adz_lib module that can be called from the main() function in the free_bookz_player module to set the value of bookz_done and you will want to add a function that can be called from the start_adz() function to get the value of bookz_done so that it knows when to stop displaying advertisements.

While this may seem more complicated, the advantage of this design is that you can include all of the coordination-related code in the adz_lib module.

5.2 An Alternative Design

Alternatively, you can use a design in which the different modules use the shared variables directly (e.g., using assignment statements). In this case, you must include coordination-related code in every module that uses the shared variables.

The advantage of this design is that it makes the sharing more apparent. The disadvantage is that the coordination-related code is not centralized.

6 Submission

You must submit all of the files (including the makefile) needed to build both the free_bookz_player and the bookz_player. Unless you have added other modules, this means you must submit the bookz_lib module, the adz_lib module, the free_bookz_player module, and the bookz_player module.

Copyright 2017