Introduce Semaphore::acquire methods

Deprecate wait() in favour of acquire(), try_acquire(),
try_acquire_for() and try_acquire_until().

Brings Semaphore more into line with CMSIS-RTOS 2 (which uses "acquire"),
itself (as it has "release"), and other classes having "try", "try for"
and "try until".

Also steps away from vague "wait" term - the primary operation here is
to acquire the semaphore, and this will of course sleep.

Author: kjbracey

TESTS/lorawan/loraradio/main.cpp

@@ -125,7 +125,7 @@ void test_set_tx_config()
 
     TEST_ASSERT_EQUAL(RF_TX_RUNNING, radio->get_status());
 
-    TEST_ASSERT_EQUAL(1, event_sem.wait(1000));
+    TEST_ASSERT_TRUE(event_sem.try_acquire_for(1000));
     TEST_ASSERT_EQUAL(EV_TX_DONE, received_event);
     received_event = EV_NONE;
 }
@@ -145,7 +145,7 @@ void test_set_rx_config()
 
     TEST_ASSERT_EQUAL(RF_RX_RUNNING, radio->get_status());
 
-    TEST_ASSERT_EQUAL(1, event_sem.wait(1000));
+    TEST_ASSERT_TRUE(event_sem.try_acquire_for(1000));
 
     // Nobody was sending to us so timeout is expected.
     TEST_ASSERT_EQUAL(EV_RX_TIMEOUT, received_event);

TESTS/mbed_drivers/lp_ticker/main.cpp

@@ -141,22 +141,20 @@ void test_multi_call_time(void)
 void test_detach(void)
 {
     LowPowerTicker ticker;
-    int32_t ret;
+    bool ret;
     const float ticker_time_s = 0.1f;
     const uint32_t wait_time_ms = 500;
     Semaphore sem(0, 1);
 
     ticker.attach(callback(sem_release, &sem), ticker_time_s);
 
-    ret = sem.wait();
-    TEST_ASSERT_TRUE(ret > 0);
+    sem.acquire();
 
-    ret = sem.wait();
+    sem.acquire();
     ticker.detach(); /* cancel */
-    TEST_ASSERT_TRUE(ret > 0);
 
-    ret = sem.wait(wait_time_ms);
-    TEST_ASSERT_EQUAL(0, ret);
+    ret = sem.try_acquire_for(wait_time_ms);
+    TEST_ASSERT_FALSE(ret);
 }
 
 /** Test single callback time via attach

TESTS/mbed_drivers/ticker/main.cpp

@@ -257,22 +257,20 @@ void test_multi_call_time(void)
 void test_detach(void)
 {
     Ticker ticker;
-    int32_t ret;
+    bool ret;
     const float ticker_time_s = 0.1f;
     const uint32_t wait_time_ms = 500;
     Semaphore sem(0, 1);
 
     ticker.attach(callback(sem_release, &sem), ticker_time_s);
 
-    ret = sem.wait();
-    TEST_ASSERT_TRUE(ret > 0);
+    sem.acquire();
 
-    ret = sem.wait();
+    sem.acquire();
     ticker.detach(); /* cancel */
-    TEST_ASSERT_TRUE(ret > 0);
 
-    ret = sem.wait(wait_time_ms);
-    TEST_ASSERT_EQUAL(0, ret);
+    ret = sem.try_acquire_for(wait_time_ms);
+    TEST_ASSERT_FALSE(ret);
 }
 
 /** Test single callback time via attach

TESTS/mbed_drivers/timeout/timeout_tests.h

@@ -78,14 +78,14 @@ void test_single_call(void)
 
     timeout.attach_callback(mbed::callback(sem_callback, &sem), TEST_DELAY_US);
 
-    int32_t sem_slots = sem.wait(0);
-    TEST_ASSERT_EQUAL(0, sem_slots);
+    bool acquired = sem.try_acquire();
+    TEST_ASSERT_FALSE(acquired);
 
-    sem_slots = sem.wait(TEST_DELAY_MS + 2);
-    TEST_ASSERT_EQUAL(1, sem_slots);
+    acquired = sem.try_acquire_for(TEST_DELAY_MS + 2);
+    TEST_ASSERT_TRUE(acquired);
 
-    sem_slots = sem.wait(TEST_DELAY_MS + 2);
-    TEST_ASSERT_EQUAL(0, sem_slots);
+    acquired = sem.try_acquire_for(TEST_DELAY_MS + 2);
+    TEST_ASSERT_FALSE(acquired);
 
     timeout.detach();
 }
@@ -110,12 +110,12 @@ void test_cancel(void)
 
     timeout.attach_callback(mbed::callback(sem_callback, &sem), 2.0f * TEST_DELAY_US);
 
-    int32_t sem_slots = sem.wait(TEST_DELAY_MS);
-    TEST_ASSERT_EQUAL(0, sem_slots);
+    bool acquired = sem.try_acquire_for(TEST_DELAY_MS);
+    TEST_ASSERT_FALSE(acquired);
     timeout.detach();
 
-    sem_slots = sem.wait(TEST_DELAY_MS + 2);
-    TEST_ASSERT_EQUAL(0, sem_slots);
+    acquired = sem.try_acquire_for(TEST_DELAY_MS + 2);
+    TEST_ASSERT_FALSE(acquired);
 }
 
 /** Template for tests: callback override
@@ -143,14 +143,14 @@ void test_override(void)
 
     timeout.attach_callback(mbed::callback(sem_callback, &sem1), 2.0f * TEST_DELAY_US);
 
-    int32_t sem_slots = sem1.wait(TEST_DELAY_MS);
-    TEST_ASSERT_EQUAL(0, sem_slots);
+    bool acquired = sem1.try_acquire_for(TEST_DELAY_MS);
+    TEST_ASSERT_FALSE(acquired);
     timeout.attach_callback(mbed::callback(sem_callback, &sem2), 2.0f * TEST_DELAY_US);
 
-    sem_slots = sem2.wait(2 * TEST_DELAY_MS + 2);
-    TEST_ASSERT_EQUAL(1, sem_slots);
-    sem_slots = sem1.wait(0);
-    TEST_ASSERT_EQUAL(0, sem_slots);
+    acquired = sem2.try_acquire_for(2 * TEST_DELAY_MS + 2);
+    TEST_ASSERT_TRUE(acquired);
+    acquired = sem1.try_acquire();
+    TEST_ASSERT_FALSE(acquired);
 
     timeout.detach();
 }
@@ -200,8 +200,8 @@ void test_no_wait(void)
     T timeout;
     timeout.attach_callback(mbed::callback(sem_callback, &sem), 0ULL);
 
-    int32_t sem_slots = sem.wait(0);
-    TEST_ASSERT_EQUAL(1, sem_slots);
+    bool acquired = sem.try_acquire();
+    TEST_ASSERT_TRUE(acquired);
     timeout.detach();
 }
 
@@ -227,9 +227,8 @@ void test_delay_accuracy(void)
     timer.start();
     timeout.attach_callback(mbed::callback(sem_callback, &sem), delay_us);
 
-    int32_t sem_slots = sem.wait(osWaitForever);
+    sem.acquire();
     timer.stop();
-    TEST_ASSERT_EQUAL(1, sem_slots);
     TEST_ASSERT_UINT64_WITHIN(delta_us, delay_us, timer.read_high_resolution_us());
 
     timeout.detach();
@@ -265,7 +264,7 @@ void test_sleep(void)
 
     bool deep_sleep_allowed = sleep_manager_can_deep_sleep_test_check();
     TEST_ASSERT_FALSE_MESSAGE(deep_sleep_allowed, "Deep sleep should be disallowed");
-    while (sem.wait(0) != 1) {
+    while (!sem.try_acquire()) {
         sleep();
     }
     timer.stop();
@@ -324,7 +323,7 @@ void test_deepsleep(void)
 
     bool deep_sleep_allowed = sleep_manager_can_deep_sleep_test_check();
     TEST_ASSERT_TRUE_MESSAGE(deep_sleep_allowed, "Deep sleep should be allowed");
-    while (sem.wait(0) != 1) {
+    while (!sem.try_acquire()) {
         sleep();
     }
     timer.stop();

TESTS/mbed_drivers/timerevent/main.cpp

@@ -65,15 +65,15 @@ class TestTimerEvent: public TimerEvent {
     using TimerEvent::insert_absolute;
     using TimerEvent::remove;
 
-    int32_t sem_wait(uint32_t millisec)
+    bool sem_try_acquire(uint32_t millisec)
     {
-        return sem.wait(millisec);
+        return sem.try_acquire_for(millisec);
     }
 };
 
 class TestTimerEventRelative: public TestTimerEvent {
 public:
-    static const int32_t SEM_SLOTS_AFTER_PAST_TS_INSERTED = 0;
+    static const bool SEM_ACQUIRED_AFTER_PAST_TS_INSERTED = false;
     TestTimerEventRelative() :
         TestTimerEvent()
     {
@@ -98,7 +98,7 @@ class TestTimerEventRelative: public TestTimerEvent {
 
 class TestTimerEventAbsolute: public TestTimerEvent {
 public:
-    static const int32_t SEM_SLOTS_AFTER_PAST_TS_INSERTED = 1;
+    static const bool SEM_ACQUIRED_AFTER_PAST_TS_INSERTED = true;
     TestTimerEventAbsolute() :
         TestTimerEvent()
     {
@@ -141,11 +141,11 @@ void test_insert(void)
     T tte;
 
     tte.set_future_timestamp(TEST_DELAY_US);
-    int32_t sem_slots = tte.sem_wait(0);
-    TEST_ASSERT_EQUAL(0, sem_slots);
+    bool acquired = tte.sem_try_acquire(0);
+    TEST_ASSERT_FALSE(acquired);
 
-    sem_slots = tte.sem_wait(TEST_DELAY_US / 1000 + DELTA);
-    TEST_ASSERT_EQUAL(1, sem_slots);
+    acquired = tte.sem_try_acquire(TEST_DELAY_US / 1000 + DELTA);
+    TEST_ASSERT_TRUE(acquired);
 
     tte.remove();
 }
@@ -170,12 +170,12 @@ void test_remove(void)
     T tte;
 
     tte.set_future_timestamp(TEST_DELAY_US * 2);
-    int32_t sem_slots = tte.sem_wait(TEST_DELAY_US / 1000);
-    TEST_ASSERT_EQUAL(0, sem_slots);
+    bool acquired = tte.sem_try_acquire(TEST_DELAY_US / 1000);
+    TEST_ASSERT_FALSE(acquired);
     tte.remove();
 
-    sem_slots = tte.sem_wait(TEST_DELAY_US * 2 / 1000 + DELTA);
-    TEST_ASSERT_EQUAL(0, sem_slots);
+    acquired = tte.sem_try_acquire(TEST_DELAY_US * 2 / 1000 + DELTA);
+    TEST_ASSERT_FALSE(acquired);
 }
 
 /** Test insert_absolute zero
@@ -188,8 +188,8 @@ void test_insert_zero(void)
     TestTimerEvent tte;
 
     tte.insert_absolute(0ULL);
-    int32_t sem_slots = tte.sem_wait(0);
-    TEST_ASSERT_EQUAL(1, sem_slots);
+    bool acquired = tte.sem_try_acquire(0);
+    TEST_ASSERT_TRUE(acquired);
 
     tte.remove();
 }
@@ -215,8 +215,8 @@ void test_insert_past(void)
     T tte;
 
     tte.set_past_timestamp();
-    int32_t sem_slots = tte.sem_wait(0);
-    TEST_ASSERT_EQUAL(tte.SEM_SLOTS_AFTER_PAST_TS_INSERTED, sem_slots);
+    bool acquired = tte.sem_try_acquire(0);
+    TEST_ASSERT_EQUAL(tte.SEM_ACQUIRED_AFTER_PAST_TS_INSERTED, acquired);
 
     tte.remove();
 }

TESTS/mbed_platform/error_handling/main.cpp

@@ -261,9 +261,9 @@ void test_error_hook()
     }
 
     MBED_WARNING1(MBED_ERROR_INVALID_ARGUMENT, "Test for error hook", 1234);
-    int32_t sem_status = callback_sem.wait(5000);
+    bool acquired = callback_sem.try_acquire_for(5000);
 
-    TEST_ASSERT(sem_status > 0);
+    TEST_ASSERT(acquired);
 }
 
 #if MBED_CONF_PLATFORM_ERROR_HIST_ENABLED && defined(MBED_TEST_SIM_BLOCKDEVICE)

TESTS/mbedmicro-rtos-mbed/event_flags/main.cpp

@@ -66,7 +66,7 @@ void send_thread_sync(EventFlags *ef)
     for (uint32_t i = 0; i <= MAX_FLAG_POS; i++) {
         const uint32_t flag = flags & (1 << i);
         if (flag) {
-            sync_sem.wait();
+            sync_sem.acquire();
             ef->set(flag);
             ThisThread::sleep_for(wait_ms);
         }

TESTS/mbedmicro-rtos-mbed/rtostimer/main.cpp

@@ -50,7 +50,7 @@ class Stopwatch: public Timer {
 
     void start(void)
     {
-        _sem.wait(0);
+        _sem.try_acquire();
         Timer::start();
     }
 
@@ -68,7 +68,7 @@ class Stopwatch: public Timer {
         if (!running) {
             return 1;
         }
-        return _sem.wait(millisec);
+        return _sem.try_acquire_for(millisec);
     }
 };
 
@@ -169,8 +169,8 @@ void test_start_again()
     osStatus status = rtostimer.start(DELAY_MS);
     TEST_ASSERT_EQUAL(osOK, status);
 
-    int32_t slots = sem.wait(DELAY_MS + DELTA_MS);
-    TEST_ASSERT_EQUAL(1, slots);
+    bool acquired = sem.try_acquire_for(DELAY_MS + DELTA_MS);
+    TEST_ASSERT(acquired);
 
 #if !MBED_TRAP_ERRORS_ENABLED
     status = rtostimer.stop();
@@ -180,8 +180,8 @@ void test_start_again()
     status = rtostimer.start(DELAY_MS);
     TEST_ASSERT_EQUAL(osOK, status);
 
-    slots = sem.wait(DELAY_MS + DELTA_MS);
-    TEST_ASSERT_EQUAL(1, slots);
+    acquired = sem.try_acquire_for(DELAY_MS + DELTA_MS);
+    TEST_ASSERT(acquired);
 
 #if !MBED_TRAP_ERRORS_ENABLED
     status = rtostimer.stop();
@@ -255,14 +255,14 @@ void test_stop()
     osStatus status = rtostimer.start(DELAY_MS);
     TEST_ASSERT_EQUAL(osOK, status);
 
-    int32_t slots = sem.wait(RESTART_DELAY_MS);
-    TEST_ASSERT_EQUAL(0, slots);
+    bool acquired = sem.try_acquire_for(RESTART_DELAY_MS);
+    TEST_ASSERT_FALSE(acquired);
 
     status = rtostimer.stop();
     TEST_ASSERT_EQUAL(osOK, status);
 
-    slots = sem.wait(DELAY_MS + DELTA_MS);
-    TEST_ASSERT_EQUAL(0, slots);
+    acquired = sem.try_acquire_for(DELAY_MS + DELTA_MS);
+    TEST_ASSERT_FALSE(acquired);
 
 #if !MBED_TRAP_ERRORS_ENABLED
     status = rtostimer.stop();

TESTS/mbedmicro-rtos-mbed/semaphore/main.cpp

@@ -46,7 +46,7 @@ void test_thread(int const *delay)
 {
     const int thread_delay = *delay;
     while (true) {
-        two_slots.wait();
+        two_slots.acquire();
         sem_counter++;
         const bool sem_lock_failed = sem_counter > SEMAPHORE_SLOTS;
         if (sem_lock_failed) {
@@ -96,8 +96,7 @@ struct thread_data {
 
 void single_thread(struct thread_data *data)
 {
-    int32_t cnt = data->sem->wait();
-    TEST_ASSERT_EQUAL(1, cnt);
+    data->sem->acquire();
     data->data++;
 }
 
@@ -140,8 +139,8 @@ void test_single_thread()
 
 void timeout_thread(Semaphore *sem)
 {
-    int32_t cnt = sem->wait(30);
-    TEST_ASSERT_EQUAL(0, cnt);
+    bool acquired = sem->try_acquire_for(30);
+    TEST_ASSERT_FALSE(acquired);
 }
 
 /** Test timeout
@@ -188,8 +187,8 @@ void test_no_timeout()
     Timer timer;
     timer.start();
 
-    int32_t cnt = sem.wait(0);
-    TEST_ASSERT_EQUAL(T, cnt);
+    bool acquired = sem.try_acquire();
+    TEST_ASSERT_EQUAL(T > 0, acquired);
 
     TEST_ASSERT_UINT32_WITHIN(5000, 0, timer.read_us());
 }
@@ -205,8 +204,8 @@ void test_multiple_tokens_wait()
     Semaphore sem(5);
 
     for (int i = 5; i >= 0; i--) {
-        int32_t cnt = sem.wait(0);
-        TEST_ASSERT_EQUAL(i, cnt);
+        bool acquired = sem.try_acquire();
+        TEST_ASSERT_EQUAL(i > 0, acquired);
     }
 }