CSC2035 (24/25)

CSC2035 Assignment 2 -
 systems programming and 
inter-process communica!on
(IPC)

CSC2035 Assignment 2 - sys-

tems programming and inter-
process communica!on (IPC)

Due
Due 13 Dec by 23:59 Points
Points 100
Available
Available 31 Oct at 0:00 - 31 Jan 2025 at 23:59

Contents
Contents

1. Introduc!on
2. Aim
3. Learning/skills outcomes
4. Important context and expecta!ons
5. The applica!on/simula!on
6. What you are given
7. What you have to do
8. Breakdown of marks
9. Deadline for submission and what to submit

1. Introduc!on
For this assignment you are provided with a par!ally
completed project to demonstrate different approaches
to maintaining the integrity of an inter-process
communica!on (IPC) applica!on. The IPC applica!on is
a collec!on of mul!ple process that communicate via a
queue of jobs that is allocated in shared memory (see
Sec!on 5).

Your task is to complete the project by implemen!ng

suppor!ng library func!ons (see Sec!on 7).

The project demonstrates both busy wai!ng and

semaphore approaches to maintaining integrity of IPC
applica!ons. This will reinforce, in prac!ce, the opera!ng
systems theory you will learn as part of this module. A
fully working solu!on will be provided a#er comple!on
of the assignment to allow you to access all learning
outcomes even if you are unable to complete the project
yourself.

2. Aim
The aim of this assignment is to give you experience of
and help you to draw lessons from:

use and implementa!on of shared memory and IPC

facili!es
simula!ng and exploring system behaviour
the modular design of systems and implementa!on
of appropriate abstrac!ons
use of the standard C library and the POSIX system
interfaces
programming to interface, where the func!ons you
have to implement are defined in a set of header
files
programming to tests, where a complete suite of
tests is provided for the libraries you implement and
the libraries that are provided for you as part of the
project
analysis of and modifica!on to an exis!ng codebase

3. Learning/skills outcomes
Prac!cal understanding and applica!on of opera!ng
systems concepts including: processes, scheduling,
resource management and IPC
C programming skills
Programming using a system interface
Implemen!ng a specified interface
Programming to test
Code comprehension skills - understanding,
analysing, using and modifying code provided by
others
An understanding of the place of your own work in
the context of a larger system
The formula!on of problems and iden!fica!on of
suitable approaches to solving them
Cogni!ve/intellectual skills and self management

4. Important context and

expecta!ons
The coursework specifica!on comprises:

this document
README files provided with the codebase that give
addi!onal instruc!ons and advice
the func!on specifica!ons wri$en in comments in
header files in the codebase

You are expected to familiarise yourself with this

material. Advice and instruc!ons, including things you
must do, may be in this document or in comments in
source code (.c or .h files) or in the README filles.
Ignoring such advice and instruc!on may lead to loss of
marks.

You are also expected to read the documenta!on

associated with relevant parts of the standard C library
and the POSIX interfaces. This documenta!on is mostly
in man (or manual) pages you access using the Unix man
command or via Web-based man pages.

You can work on this assignment on any POSIX-

compliant system (including a virtual machine). See the
module resource on se%ng up your C programming
environment for informa!on on the different ways to do
this. This means that we will use this linux environment
to compile and run your solu!on when we are marking
your work. Therefore, regardless of how you choose to
work, you should test your solu!on on on this provided
VM before you submit it.

There are references to the "user" in the materials

provided. This means a programmer (including yourself)
who uses a library func!on in their program. The library
func!on may be from a system library, may be one of
the func!ons provided for you or may be one of the
func!ons that you have to implement. In all cases, the
user of the func!on is the programmer who includes a
call to the func!on in their code (as opposed to an end
user of an applica!on). Some!mes the process calling a
func!on is referred to as the user of the func!on.

You are comple!ng the implementa!on of libraries notnot

an applica!on program. Applica!ons and tests that use
the libraries are provided for you. There
There is
is no
no need
need to
to
write
write any
any other
other applica!on
applica!on programs
programs. That is, you
should not
not write a main func!on for this assignment.

Library func!ons do not normally produce output to

console because the des!na!on for output is an
applica!on-level concern. Therefore, there should not
not
be any prin& or perror or other such statements that
produce output to stdout or stderr in the
implementa!ons you submit. If you use such output for
debugging when you are working on the assignment,
remove
remove itit before
before submi%ng
submi%ng youryour solu!on
solu!on.

Each library in the codebase has a corresponding test (in

the test directory). These tests give you valuable
feedback on whether your implementa!on is successful.
The test source code is also instruc!ve. From the test
source code, you can o#en work out what a library has
to do and even some of how it should be implemented.

There will be two releases of the project codebase:

Release 1 is the complete codebase for the libraries

to develop along with an almost complete suite of
tests. Tests missing from release 1 are for the
queueing libraries.
When tes!ng the joblog.c file, specifically
the joblog\_write func!on, the expected output
appears to be incorrect with README. So what
README\_joblog\_ example.txt states is the correct or

described output to pass the test.

So in the log with a process id of 0, the test case
expected a process id of 1. All the other tests
should pass correctly.
Release 2 will complete the test suite and provide
the applica!ons that use the libraries you develop.
This may be separated into two releases, with tests
suite first then the applica!ons. (release 2 is
available)

This project can be seen as a collabora!ve development

with me and it is normal in a collabora!ve development
for there to be staging of releases. This mirrors industry
prac!ce. Do not
not wait for the release 2 to start work on
the assignment. You can work on all parts of the
assignment (including queueing aspects) without release
2. You can even write your own queueing tests if you
wish. That is, the
the staging
staging of
of releases
releases does
does not
not
mean
mean aa delay
delay toto your
your work
work. When you have release
2, you will be able to complete all tes!ng and the
correc!on of your work in order to pass the release 2
tests. Do not
not submit your work un!l you have tested it
with the complete test suite provided in release 2.

Altogether, the main codebase comprises over 20 (.c

and .h) source code files (of which you are expected to
complete the implementa!on of 5 files). In addi!on,
there are over 20 source code files in the test directory.
In a project of this size, it is possible that there are bugs
in the code that is provided for you. It is possible
therefore that bug fixes will be released when you are
working on the assignment. This is also normal.. In
addi!on, advice, clarifica!on, documenta!on and
README files may be released a#er release of the ini!al
codebase. Once again, this is normal. This will give you
experience of how in a real world projects things can
change during development. The specifica!on of the
func!ons you have to implement will not change and no
changes to the codebase will be released in the week
before the assignment is due..

You
You must
must not
not change
change func!on
func!on signature
signature in in header
header
(.h)
(.h) files
files. Header files will only change if I release an
update that changes them.

Contact us (csc2035cwsupport@group.newcastle.ac.uk)
if you need clarifica!on of the project requirements or
need help interpre!ng documenta!on or need help to
solve programming problems.

5. The applica!on/simula!on
As shown in the following figure, the overall project
simulates an applica!on in which a set of one or more
producer processes create jobs to submit (enqueue) to a
priority job queue for one or more consumer processes
to dequeue and process. The use of a priority queue
means that each job has a priority associated with it and
jobs will be dequeued in priority order (highest priority
job first). The job queue is in shared memory. In addi!on
each process (producer or consumer) has a private
persistent log of jobs that they have produced (if they
are a producer) or consumed (if they are a consumer).
Many common client/server applica!ons follow this
model of one or more producers (clients) submi%ng
work to be done by a one or more consumers (servers).

The overall applica!on proceeds as follows :

While a producer process has jobs to be done, they

produce a job, assign a priority level to the job,
enqueue the job on the job queue and log the job in
their private log. A producer is made to wait to
enqueue a job if the queue is full. If there are
mul!ple producers, they should not able to
overwrite each other's jobs despite sharing the same
queue.
While there are jobs to consume, a consumer
process dequeues the next job from the queue
(which will be the job with the highest prioirty on the
queue), logs the job in their private log and
processes the job. A consumer ismade to wait to
dequeue a job if the queue is empty. If there are
mul!ple consumers, each job is only consumed by
one consumer despite sharing the queue with the
other consumers.

A job is represented by the following a$ributes:

the process id (pid) of the producer of the job

a job id generated by the producer of the job that is
locally unique to that producer
a priority level with 1 being the highest priority, then
2 and so on. Priori!es are not unique. Two dis!nct
jobs may have the same priority.
a job label - an applica!on-specific string that, for
example, may describe the job

The combina!on of job pid and id means that, assuming

integrity constraints are maintained, each job will be
globally unique even when mul!ple producers are
producing jobs. The job id that is locally unique for a
given producer is made globally unique for all producers
by qualifying the job id with the producer's globally
unique pid.

In a real-world version of the applica!on, the

combina!on of pid and job id could be replaced by an
absolute URL that is qualified by the producer's domain
name. The label could be replaced by a URL link to a job
specifica!on.

The C applica!on code for the producer and consumer

processes that drive the simula!on will be provided for
you in the release 2 (or subsequent release) of the
assignment. Your task is to complete libraries that
support the simula!on (see Sec!on 7). You are not not
wri!ng the whole applica!on (or all of the library code).
You do not
not write the producer or consumer
applica!ons. Applica!on code in release 1 is the test
suite provided for you to test your library code.

The overall integrity constraint of the applica!on is that

producers should not produce duplicate jobs and each
job should only be consumed once by one consumer.
That is, no two consumers should consume the same
job. If you complete the libraries specified in Sec!on 7,
when the producer and consumer applica!ons are
released you you will have a project that demonstrates
whether this constraint holds for different approaches to
concurrency control.

Whether integrity is maintained can be verified by

checking whether the states of log files a#er a
simula!on run sa!sfy the following condi!ons:

1. Jobs
Jobs are
are well-formed
well-formed: entries in logs are as
specified in the joblog.h file.
2. Logs
Logs are
are sets
sets: no producer log contains duplicate
entries and no consumer log contains duplicate
entries
3. No
No jobs
jobs are
are lost
lost: every job that appears in a
producer log has a corresponding entry in one of the
consumer logs
4. Consumers
Consumers do do not
not create
create jobs
jobs: every job that
appears in a consumer log has a corresponding entry
in one of the producer logs
Condi!ons 2, 3 and 4 mean that the union of
producer logs equals the union of consumer logs.
That is, for producer logs P0 to Pn and consumer
logs C0 to Cm:
P0 ∪ P1 ∪ ... ∪ Pn = C0 ∪ C1 ... ∪ Cm
5. There
There isis no
no duplica!on
duplica!on of of jobs
jobs between
between
consumers.
consumers. Each job is consumed by one and only
one consumer. That is, each pair-wise intersec!on of
the set of consumer logs is the empty set:
for each and every pair of consumer logs Ci and
Cj, Ci ∩ Cj = ∅

In addi!on, from the set of jobs in the queue at any one

!me, jobs are consumed in priority order. This is not an
integrity constraint and it does not imply a total ordering
of all jobs by priority. It simply means that, if the queue
implementa!on is correct, for the set of jobs in the
queue at any one !me, the highest prioirty job is
dequeued first. This will be verified by queueing tests.

Further informa!on about the overall simula!on, how to

run it and how to analyse the process logs, as well as
how to run tests of libraries, will be provided in
README files. When the producer and consumer
applica!ons are released, scripts will be provided for you
to run the applica!ons and to analyse logs a#er each
simula!on run.

A#er comple!on of the assignment, and as part of your

feedback, a working solu!on will be released. This will
allow you to access all the learning outcomes even if
you are unable to complete the assignment correctly.

6. What you are given

The codebase is provided in two releases.

Release 1 - the ini!al codebase

Release 1 is the ini!al codebase that includes all the
libraries that you have to complete along with tests for
libraries.

Download the ini!al release of the codebase as either a

zip file or tar-gzipped archive:

csc2035-assignment1-r01.zip ,, or csc2035-
assignment1-r01.tgz

This contains:

an ini!al README file that tells you how to build

and test the libraries you implement
a Makefile and associated configura!on files to build
the project
the source code for the following project libraries,
including the .c files you have to complete (for the
libraries in bold):
ipc - an encapsula!on of shared memory
ipc_jobqueue
ipc_jobqueue - a shared memory wrapper for a
job queue
job
job - the representa!on of a job
joblog
joblog - a facility to log jobs to file
pri_jobqueue
pri_jobqueue - a priority job queue
proc - the representa!on of a process in the
applica!on
sem_jobqueue
sem_jobqueue - a semaphore based monitor
for controlled access to a shared memory job
queue
shobject_name - a u!lity to generate well-formed
names for shared memory objects
the test source code for the above libraries in a test
sub-directory. The queueing tests (for ipc_jobqueue,
pri_jobqueue and sem_jobqueue) are currently
incomplete. They simply output that the tests are
skipped. Complete tests will be provided in release
2. Do not let this delay your work on the assignment
or even on the queueing implementa!ons. You You can
can
make
make progress
progress on on all
all aspects
aspects ofof the
the project
project
that
that you
you have
have toto implement
implement without
without the
the
complete
complete tests.
tests.
a shell script (runtests.sh), to run tests.

You start by reading the ini!al README file:

README01.txt
README01.txt

Release 2 - to complete the codebase

Release 2 completes the codebase with the queue test
suites and the simula!on applica!ons to demonstrate
different approaches to concurrency controll. The code
for release 2 is now made available.

7. What you have to do

You have to complete the implementa!on of the
func!ons with a TODO comment in the following .c
files.

job.c - the representa!on of a job

joblog.c - logging func!ons
pri_jobqueue.c - the defini!on of and func!ons to
manipulate a queue of jobs based on a fixed-sized
array with priority order dequeing of jobs. It is your
implementa!on decision whether jobs are stored in
the queue in priority order. The requirement is that
they are dequeued in priority order. See
documenta!on in pri_jobqueue.h and pri_jobqueue.c
for further informa!on.
ipc_jobqueue.c - wrapper func!ons for a queue of
jobs that is stored in shared memory for IPC
sem_jobqueue.c - wrapper func!ons for a queue of
jobs that is stored in shared memory and that is
protected by semaphores to sa!sfy integrity
constraints

If you think it will help to reduce code duplica!on or

simplify logic, you may define your own private helper
func!ons in the above files.

Do not
not modify any files other than those listed. Do not
modify any func!ons other than those specified by a
TODO comment in the files listed. Comments in files
clearly state which files you should edit and which
func!ons in those files you should implement. A
"TODO" comment means that you have to implement a
func!on or complete its implementa!on. A "DO NOT
EDIT" comment means you do not edit the file,
declara!on or func!on with which it is associated.

The specifica!on of the func!ons you have to

implement is given in corresponding header (.h) files, i.e.
see joblog.h for the specifica!on of the func!ons in
joblog.c.

README files, this assignment specifica!on, comments

and hints in the .c files etc. provide addi!onal guidance
for comple!ng the assignment.

How to work and programming to

test
1. Compile the project and run the tests as instructed
in the README file provided. You will see that tests
fail. Your job is to complete the project un!l no tests
fail.
2. The suggested order to implement the libraries is:
1. job.c because the other libraries depend on job.c
2. joblog.c because it does not rely on an
understanding or queueing or IPC
3. pri_jobqueue.c because the other queue
implementa!ons depend on pri_jobqueue.c
4. ipc_jobqueue.c
5. sem_jobqueue.c
3. For each .c library file, a#er making changes, compile
the project again and run the tests.
4. Keep working un!l all tests succeed for a given
library. You can run tests for all code or for an
individual library file.

That is, program to the tests provided. README files

gives instruc!ons on compiling and running test
programs and provide examples of expected output.

A note on dependencies
There are the following dependencies between the
libraries:

joblog.c depends on the "public" interface of job.c (as

defined in job.h)
pri_jobqueue.c depends on the "public" interface of
job.c (as defined in job.h)
ipc_jobqueue.c and sem_jobqueue.c depend on the
"public" interface of pri_jobqueue.c (as defined in
pri_jobqueue.h)

These dependencies mean, for example, it is not

possible to properly test joblog.c without a working
implementa!on of job.c. However, even if you cannot
test it properly, you can a$empt to implement joblog.c
without implemen!ng job.c because joblog.c will invoke
func!ons in the interface defined in job.h and not access
implementa!on detail. That is, dodo not
not give
give up
up just
just
because
because you
you dodo not
not know
know how
how toto implement
implement
job.c
job.c. Move on to the libraries, parts of which may be
implemented in terms of the job.h interface.

When we mark your work we will test and mark each

component independently. That is, for example, we will
test and mark your implementa!on of joblog.c with the
specimen solu!on to job.c and not your solu!on and so
on. This ensures you are not disadvantaged by the
dependencies and that an incorrect solu!on to job.c
does not prevent you gaining full marks for joblog.c, for
example.

Addi!onal advice
This project does not involve complicated or
innova!ve programming. It It is
is mainly
mainly an
an exercise
exercise
in
in code
code and
and project
project comprehension
comprehension. The difficult
part is understanding what you have to do, and
understanding how to apply examples and other
code you have been given. This does not mean you
should delay star!ng. It will take !me to understand
all the informa!on you have been given and to
determine what you have to do. You You will
will find
find this
this
assignment
assignment veryvery difficult,
difficult, if if not
not impossible,
impossible, if if
you
you leave
leave it
it to
to the
the last
last week
week before
before
submission
submission date.
date.
Start
Start now
now (teaching week 3) with familiarising
yourself with the code you have been given and
processing all the other informa!on you have been
given.
Do not reinvent the wheel. It is OK to use and adapt
code that is provided in examples in the module
and/or in the codebase provided (including the test
code). Test code is a good place to look for what is
expected of a func!on. It may also give you ideas for
how to implement the func!on. And don't just look
at the tests directly related to a library. That is, look
at test_job.c to help with implementa!on of job.c
and also look at test_joblog.c and
test_pri_jobqueue.c (when provided). These other
tests may have useful example code that will help
with the implementa!on of job.c.
As with any assignment, do do not
not use
use or
or copy
copy each
each
other's
other's code
code.
Research the C libraries for func!ons you use. Look
at the man pages for any func!ons from the C and
system libraries you use. Understand what the return
values of library func!ons mean and what the error
condi!ons are.
You will get the most out of this project if you also
do forma!ve work for the module and a$end
associated workshops and demonstra!ons.

A note on commen!ng code

You do not
not need to comment your code. In fact, it is
be$er that you do not
not comment your code. You can add
comments for your benefit but it would be be$er to
remove them before submi%ng your work. In any case,
we will ignore comments that you add to code.

The reason for this is that comments can easily get out
of sync with the code that they comment. This is a
maintenance problem. Code should be simple and clear
enough to explain itself. Therefore, in general, you
should only provide comments to the external interface
to your code. These are already provided for you in this
project and there is, therefore, no need for addi!onal
commen!ng.

8. Breakdown of marks
The total mark for this assignment is 100. It is worth
50% of the coursework component of the module and
17% of the module mark.

The indica!ve breakdown of marks for each part of the

assignment is as follows:

ipc_jobqueue.c - 10 marks
job.c - 30 marks
joblog.c - 15 marks
pri_jobqueue.c - 25 marks
sem_jobqueue.c - 20 marks

For full marks your solu!on must:

Compile without compiler warnings and run on the

reference sysem cs-linux.ncl.ac.uk, and
Pass tests for the above files (some of which may be
more comprehensive than the tests provided with
the codebase), and
Comply with instruc!ons given in this specifica!on
and related material (including in relevant .h files, .c
files and README files), and
Demonstrate good programming prac!ce par!cularly
with respect to non-func!onal aspects. Good
prac!ce includes (but is not restricted to):
Not overcomplica!ng solu!ons
Guarding against memory leaks
Safe use and choice of system and C library
func!ons
Where appropriate, programming defensively
with respect to input parameters to func!ons
and return values of func!ons you use. "Where
appropriate" means that there is a trade-off
between programming defensively and not over-
complica!ng your solu!ons. However, you
 should guard against propaga!on of errors to the
underlying system. The specifica!on of func!ons
will give some indica!on of what is expected in
terms of managing errors and erroneous input.

9. Deadline for submission and

what to submit
Your coursework must be submi$ed to the
the NESS
NESS
system
system byby 23:59
23:59 onon Thursday
Thursday 14
14 December
December
2023
2023. The deadline is rigorously imposed by NESS.
Work that is a few seconds beyond the submission
deadline will be flagged as late.

You submit your versions of the files listed in Sec!on 7

in a directory called csc2035-assignment1-submit in a
zip or tar-gzipped archive. That is, a zip archive called
csc2035-assignment1-submit.zip or a tar-gzipped
archive called csc2035-assignment1-submit.tgz with the
following contents:

csc2035-assignment2-submit/
ipc_jobqueue.c
job.c
joblog.c
pri_jobqueue.c
sem_jobqueue.c

You can use the command:

make submission

to create your submission archive. The csc2035-

assignment1-submit.zip archive created by "make
submission" will be in a submission directory of your
project directory.

Do not
not submit any other files. Anything other than the
files listed above will be ignored. Submi%ng your files in
the csc2035-assignment2-submit directory means that
they can be tested automa!cally by our markers.

Each of the .c file should start with the following

comment:

/*
* Replace the following string of 0s with your stu
dent number
* 000000000
*/

where, as instructed, you replace

replace 000000000
000000000 with
with
your
your student
student number
number.

Do
Do not
not submit
submit your
your work
work un!l
un!l you
you have
have tested
tested it
it
on
on Arzue
Arzue Linux
Linux VM
VM with
with the
the complete
complete tests
tests in
in
release
release 22 of
of the
the codebase.
codebase.