2.1 Part 1: The Wallet

For the first two parts of this MP, you will be working in the file wallet.py. You will implement the wallet library, which has only a few basic requirements:

1. Your wallet initially starts empty, with 0 of all resources.
2. Your wallet can accept any resource (identified by any string). The user of your library will call wallet_change and supply a delta to change your resource by a certain delta. You may assume that every delta is an int.
3. You must NEVER let any resource in the wallet go negative. You must NOT return from wallet_change until you can satisfy the request (another thread must add to your wallet).
4. You may have multiple wallets at once. All state of your wallet must be maintained in your class Wallet, not in global variables or the like.
5. Finally, and most importantly, many threads will be accessing your wallet(s) at the same time. You must ensure the data in your wallet is correct by ensuring accesses to your wallet are properly synchronized.

The starter code has a simple class Wallet for you to extend with empty method bodies for you to implement.

2.2 Part 2: both blocking and non-blocking methods

change must block if there are not enough resources to be immediately satisfied. This must move the thread to a blocked state using one or more of the synchronization tools from the threading library, such as locks and conditional variables.

# Example of "busy waiting" (wasting CPU cycles), which is NOT allowed:
while resource_count < delta:
    pass # do nothing 

# Example of "sleep waiting" (wasting CPU cycles or time, or a bit of both), which is NOT allowed:
while resource_count < delta:
    time.sleep(0.001)

try_change must not block, but also must not make resources negative. If change would block, try_change will instead immediately return False.

2.3 Part 3: multi-resource transactions

Sometimes we want to perform a multi-resource transaction as a single atomic operation. For example, if a group of friends agree to split the bill at a restaurant we only want to perform the transaction if every friend has enough money for their part of the bill; otherwise, we shouldn’t get any food.

The transaction method takes multiple keyword arguments, each with a resource name as a the keyword and the delta change to that resource as the value. It performs all of these changes at once, blocking if needed until they can be done in one action. You may assume that every delta is an int.

For example, if Luther, Wade, and Carl agreed to split a $45 restaurant bill we might run wallet.transaction(Luther=-15, Wade=-15, Carl=-15, Restaurant=+45); this would block until all three of Luther, Wade, and Carl have at least 15 in their accounts and then reduce all three by 15 and increase the restaurant by 45 all at once, not allowing any other threads to do anything else to these four accounts in between the various -15 and +45 operations.

4.1 Stage 1: custom tests

The best way to see if your code works and fix it when it does not is do your own tests.

import wallet
w = wallet.Wallet()
print(w.change('thingy',4))
print(w.change('thingy',-2))

apt update
apt install telnet

Connected to localhost.
Escape character is '^]'.

Connected to localhost.
Escape character is '^]'.
GET baz
0
MOD baz 6
6
MOD baz 4
10
GET baz
10
EXIT
Connection closed by foreign host.

4.2 Stage 2: prebuilt files

The MP comes with several files that interact with the wallet in longer runs, verifying that your code works even in long-running sessions. These are:

hedgehog-simple.py

uses change and get

Two threads; one generates 🐛, the other consumes 🐛 to generate 🦔.

hedgehog-rat.py

uses change, get, and try_change

Four threads; one generates 🐛, one generates 🌽, one other consumes 🐛 to generate 🦔, and one tries to consume 🐛, but falls back on 🌽 if there are no 🐛, to generate 🐀.

Because thread scheduling is unpredictable, the number of times that 🐀s eat all the 🐛s before a 🦔 can will vary by run. There’s a very small chance that the program will freeze because it ran out of 🐛 and is still trying to make more 🦔.

degree.py

uses change, get, and transaction

Many threads.

Some threads just produce things: one generates ☘️ (and an occasional 🍀); another 🧰 (and an occasional 💎); another 🍏; another 🧬.

Some threads consume some things to generate other things, such as making a 📗 out of 1×🍏, 1×🍀, 10×☘️, and 5×🧬.

Eventually, these result in a 🎓.

gacha.py

uses change, get, and transaction

Many threads; like degree.py, some produce things and others convert them into other things.

This file mimics 90 draws of Genshin Impact’s 3-, 4-, and 5-star system with a pity system that guarantees an item of a certain star-level.

ping-pong.py

uses change

Two resources and two threads. One thread consumes one resource and produces the other, the other thread is the other way around. The result is each thread does one action then waits for the other, bouncing resources back and forth. This has proven useful for debugging some edge cases.

ping-pong-transaction.py

uses change and transaction

Like ping-pong.py, but using transactions instead of pairs of changes. Randomly decides which thread has the needed resource to start the exchanges.

4.3 Stage 3: pytest

We provide a suite of automated tests designed to be run with the pytest library, which is preinstalled on your Docker image.

python3 -m pytest

You can also run just one part’s tests with python3 -m pytest test_part_1.py.

You can also run just a single test with python3 -m pytest test_part_1.py -k initially_empty.

These tests use several odd constructs to ensure they terminate even if your code blocks and are not likely to be easy to use in debugging directly. Some of them also require that your wallet.py does not print anything. If you fail one or more of these tests, you are best-off copying the relevant parts of the test into your own test program rather than trying to debug the test itself.

python3 -m pip install pytest