3. Create and wake a pendable function#

pw_async2: Cooperative async tasks for embedded

Currently, your vending machine immediately dispenses an item after receiving coins. In this step, you modify your app to let customers choose what to buy. Along the way you will learn how to correctly wake up a task that is waiting for input like this. You will also gain some experience implementing a Pend() function yourself.

Stub the Keypad class#

The hardware simulator sends you keypad events via async calls to key_press_isr(). The simulator sends integer values between 0 and 9 that indicate which keypad button was pressed. Your mission is to process these keypad events safely and to allow your task to wait for keypad numbers after receiving coins.

Use the keypad in main.cc:

Declare a global keypad instance
Update key_press_isr() to handle keypad input events by invoking keypad.Press(key)
Pass a reference to the keypad when creating your task instance

Set up the keypad class in vending_machine.h (as well as a data member for tracking how many coins have been inserted):

Declare the stub Keypad class:

class Keypad {
 public:
  constexpr Keypad() : key_pressed_(kNone) {}

  // Pends until a key has been pressed, returning the key number.
  //
  // May only be called by one task.
  pw::async2::Poll<int> Pend(pw::async2::Context& cx);

  // Record a key press. Typically called from the keypad ISR.
  void Press(int key);

 private:
  // A special internal value to indicate no keypad button has yet been
  // pressed.
  static constexpr int kNone = -1;

  int key_pressed_;
};

Set up a private keypad_ member for VendingMachineTask
Add a Keypad& argument to the VendingMachineTask constructor parameters and use it to initialize the keypad_ member
Set up an unsigned coins_inserted_ data member in VendingMachineTask that tracks how many coins have been inserted and initialize coins_inserted_ to 0 in the constructor

Create a stub implementation and integrate it (as well as the coin count data member) in vending_machine.cc:

Create a stub Keypad implementation:
1pw::async2::Poll<int> Keypad::Pend(pw::async2::Context& cx) { 2 return key_pressed_; 3} 4 5void Keypad::Press(int key) {}
Notice how the Pend member function just immediately returns the value of key_pressed_, which is only ever set to kNone (-1). We will fix that later.
Update VendingMachineTask::DoPend() to check if coins have already been inserted before it pends for coins (coin_slot_.Pend(cx))
Wait for keypad input by invoking keypad_.Pend(cx)) after coins have been inserted

Verify the stub implementation#

Run the app:
```
bazelisk run //pw_async2/codelab
```
Press c Enter to insert a coin.

You should see a log stating that -1 was pressed. This is expected since the KeyPad::Pend() stub implementation returns key_pressed_, which was initialized to kNone (-1).
```
INF  Welcome to the Pigweed Vending Machine!
INF  Please insert a coin.
c
INF  Received 1 coin.
INF  Please press a keypad key.
INF  Keypad -1 was pressed. Dispensing an item.
```

Handle keypad events#

Now, let’s update the Keypad implementation to actually handle key presses.

Protect keypad data access in vending_machine.h:

Include the pw_sync/interrupt_spin_lock.h and pw_sync/lock_annotations.h headers
Add a pw::sync::InterruptSpinLock lock_ private member to Keypad
Guard key_pressed_ with the spin lock with PW_GUARDED_BY

Since the keypad ISR is asynchronous, you’ll need to synchronize access to the stored event data. For this codelab, we use pw::sync::InterruptSpinLock which is safe to acquire from an ISR in production use. Alternatively you can use atomic operations.

We use PW_GUARDED_BY to add a compile-time check to ensure that the protected key press data is only accessed when the spin lock is held.

Implement keypress handling in vending_machine.cc:

In Keypad::Pend(), attempt to read the keypress data
In Keypad::Press(), store the keypress data

It’s so simple… what could go wrong?

Test the keypad implementation#

Run the app:
```
bazelisk run //pw_async2/codelab
```

Press c Enter to insert a coin.

INF  Welcome to the Pigweed Vending Machine!
INF  Please insert a coin.
c
INF  Received 1 coin.
INF  Please press a keypad key.

   ▄████▄      ██▀███      ▄▄▄           ██████     ██░ ██
  ▒██▀ ▀█     ▓██ ▒ ██▒   ▒████▄       ▒██    ▒    ▓██░ ██▒
  ▒▓█ 💥 ▄    ▓██ ░▄█ ▒   ▒██  ▀█▄     ░ ▓██▄      ▒██▀▀██░
  ▒▓▓▄ ▄██▒   ▒██▀▀█▄     ░██▄▄▄▄██      ▒   ██▒   ░▓█ ░██
  ▒ ▓███▀ ░   ░██▓ ▒██▒    ▓█   ▓██▒   ▒██████▒▒   ░▓█▒░██▓
  ░ ░▒ ▒  ░   ░ ▒▓ ░▒▓░    ▒▒   ▓▒█░   ▒ ▒▓▒ ▒ ░    ▒ ░░▒░▒
    ░  ▒        ░▒ ░ ▒░     ▒   ▒▒ ░   ░ ░▒  ░ ░    ▒ ░▒░ ░
  ░             ░░   ░      ░   ▒      ░  ░  ░      ░  ░░ ░
  ░ ░            ░              ░  ░         ░      ░  ░  ░
  ░

pw_async2/dispatcher_base.cc:151: PW_CHECK() or PW_DCHECK() FAILED!

  FAILED ASSERTION

    !task->wakers_.empty()

  FILE & LINE

    pw_async2/dispatcher_base.cc:151

  FUNCTION

    NativeDispatcherBase::RunOneTaskResult pw::async2::NativeDispatcherBase::RunOneTask(Dispatcher &, Task *)

  MESSAGE

    Task 0x7ffd8ddc2f40 returned Pending() without registering a waker

To prevent obviously incorrect usage, the pw_async2 module asserts if you return Pending() without actually storing a Waker, because it means your task has no way of being woken back up.

Store a waker#

In general, you should always store a Waker before returning Pending(). A waker is a lightweight object that allows you to tell the dispatcher to wake a task. When a Task::DoPend() call returns Pending(), the task is put to sleep so that the dispatcher doesn’t have to repeatedly poll the task. Without a waker, the task will sleep forever.

Declare a waker in vending_machine.h:

Include the pw_async2/waker.h header
Add a pw::async2::Waker waker_ private member to the Keypad class

Use the waker in vending_machine.cc:

In Keypad::Pend() store the waker before returning Pending():
```
PW_ASYNC_STORE_WAKER(cx, waker_, "keypad press");
```

The last argument should always be a meaningful string describing the wait reason. In the next section you’ll see how this string can help you debug issues.

Tip

See Setting up wakers for an overview of all of the different ways that you can set up wakers.

Forget to wake the task#

You’ve set up the waker but you’re not using it yet. Let’s see what happens.

Run the app:
```
bazelisk run //pw_async2/codelab
```
Press c Enter to insert a coin.
Press 1 Enter to select an item.

You should see output like this:
```
INF  Welcome to the Pigweed Vending Machine!
INF  Please insert a coin.
c
INF  Received 1 coin.
INF  Please press a keypad key.
1
```
Nothing happens, not even an assertion! This time there is no crash! Why??

Answer

The problem is that pw_async2 has no way of knowing when the task is ready to be woken up.

The reason pw_async2 can detect forgetting to store the waker, on the other hand, is because it happens during a pw_async2-initiated call into your code, so there can be a postcondition check.
Debug this issue by pressing d Enter:

You should see output like this:
```
d
INF  pw::async2::Dispatcher
INF  Woken tasks:
INF  Sleeping tasks:
INF    - VendingMachineTask:0x7ffeec48fd90 (1 wakers)
INF      * Waker 1: keypad press
```
This shows the state of all the tasks registered with the dispatcher. The last line is the wait reason string that you provided when you registered the waker. We can see that the vending machine task is still sleeping.

Tip

If you use pw_async2 in your own project, you can get this kind of debug information by calling LogRegisteredTasks.

If you don’t see the reason messages, make sure that PW_ASYNC2_DEBUG_WAIT_REASON is not set to 0.

Wake the task#

Fix the issue in vending_machine.cc:
- Invoke the Wake() method on the Waker:
```
1void Keypad::Press(int key) {
2  std::lock_guard lock(lock_);
3  key_pressed_ = key;
4  std::move(waker_).Wake();
5}
```
  By design, the Wake() call consumes the Waker. To invoke Wake() you must use std::move() to make it clear that the task can be only woken once through a given waker.
  
  Wakers are default-constructed in an empty state, and moving the value means the location that is moved from is reset to an empty state. If you invoke Wake() on an empty Waker, the call is a no-op.
Verify the fix:
```
bazelisk run //pw_async2/codelab
```
Press c Enter to insert a coin.

Press 1 Enter to select an item.

You should see keypad input working correctly now:

INF  Welcome to the Pigweed Vending Machine!
INF  Please insert a coin.
c
INF  Received 1 coin.
INF  Please press a keypad key.
1
INF  Keypad 1 was pressed. Dispensing an item.

Tip

You can also end up in a “task not waking up” state if you destroy or otherwise clear the Waker instance that pointed at the task to wake. LogRegisteredTasks() can also help here by pointing to a problem related to waking your task.

Next steps#

Continue to 4. Use a state machine to learn how to manage the rapidly increasing complexity of your code.

Checkpoint#

At this point, your code should look similar to the files below.

main.cc

#include "coin_slot.h"
#include "hardware.h"
#include "pw_async2/dispatcher.h"
#include "vending_machine.h"

namespace {

codelab::CoinSlot coin_slot;
codelab::Keypad keypad;

}  // namespace

// Interrupt handler function invoked when the user inserts a coin into the
// vending machine.
void coin_inserted_isr() { coin_slot.Deposit(); }

// Interrupt handler function invoked when the user presses a key on the
// machine's keypad. Receives the value of the pressed key (0-9).
void key_press_isr(int key) { keypad.Press(key); }

// Interrupt handler function invoked to simulate the item drop detector
// detecting confirmation that an item was successfully dispensed from the
// machine.
void item_drop_sensor_isr() {
  // In Step 5 you will uses this as part of a new Dispense task that runs
  // the dispenser motor until an item drops, or you time out on the vend
  // operation.
}

int main() {
  pw::async2::Dispatcher dispatcher;
  codelab::HardwareInit(&dispatcher);

  codelab::VendingMachineTask task(coin_slot, keypad);
  dispatcher.Post(task);

  dispatcher.RunToCompletion();

  return 0;
}

vending_machine.cc

#include "vending_machine.h"

#include "pw_async2/try.h"
#include "pw_log/log.h"

namespace codelab {

pw::async2::Poll<int> Keypad::Pend(pw::async2::Context& cx) {
  std::lock_guard lock(lock_);
  int key = std::exchange(key_pressed_, kNone);
  if (key != kNone) {
    return key;
  }
  PW_ASYNC_STORE_WAKER(cx, waker_, "keypad press");
  return pw::async2::Pending();
}

void Keypad::Press(int key) {
  std::lock_guard lock(lock_);
  key_pressed_ = key;
  std::move(waker_).Wake();
}

pw::async2::Poll<> VendingMachineTask::DoPend(pw::async2::Context& cx) {
  if (!displayed_welcome_message_) {
    PW_LOG_INFO("Welcome to the Pigweed Vending Machine!");
    PW_LOG_INFO("Please insert a coin.");
    displayed_welcome_message_ = true;
  }

  if (coins_inserted_ == 0) {
    PW_TRY_READY_ASSIGN(unsigned coins, coin_slot_.Pend(cx));
    PW_LOG_INFO("Received %u coin%s.", coins, coins > 1 ? "s" : "");
    PW_LOG_INFO("Please press a keypad key.");
    coins_inserted_ += coins;
  }

  PW_TRY_READY_ASSIGN(int key, keypad_.Pend(cx));
  PW_LOG_INFO("Keypad %d was pressed. Dispensing an item.", key);

  return pw::async2::Ready();
}

}  // namespace codelab

vending_machine.h

#pragma once

#include "coin_slot.h"
#include "pw_async2/context.h"
#include "pw_async2/poll.h"
#include "pw_async2/task.h"
#include "pw_async2/waker.h"
#include "pw_sync/interrupt_spin_lock.h"
#include "pw_sync/lock_annotations.h"

namespace codelab {

class Keypad {
 public:
  constexpr Keypad() : key_pressed_(kNone) {}

  // Pends until a key has been pressed, returning the key number.
  //
  // May only be called by one task.
  pw::async2::Poll<int> Pend(pw::async2::Context& cx);

  // Record a key press. Typically called from the keypad ISR.
  void Press(int key);

 private:
  // A special internal value to indicate no keypad button has yet been
  // pressed.
  static constexpr int kNone = -1;

  pw::sync::InterruptSpinLock lock_;
  int key_pressed_ PW_GUARDED_BY(lock_);
  pw::async2::Waker waker_;  // No guard needed!
};

// The main task that drives the vending machine.
class VendingMachineTask : public pw::async2::Task {
 public:
  VendingMachineTask(CoinSlot& coin_slot, Keypad& keypad)
      : pw::async2::Task(PW_ASYNC_TASK_NAME("VendingMachineTask")),
        coin_slot_(coin_slot),
        displayed_welcome_message_(false),
        keypad_(keypad),
        coins_inserted_(0) {}

 private:
  // This is the core of the asynchronous task. The dispatcher calls this method
  // to give the task a chance to do work.
  pw::async2::Poll<> DoPend(pw::async2::Context& cx) override;

  CoinSlot& coin_slot_;
  bool displayed_welcome_message_;
  Keypad& keypad_;
  unsigned coins_inserted_;
};

}  // namespace codelab