Simplify circular buffer threadsafe

[r-owen]

Pull Request Template

Description

This improves the "threadsafe" version of the circular buffer code in two ways, both based on the fact that the "threadsafe" version uses the "waste one element" technique to disambiguate full vs empty:

• It asserts that size > 1 in circular_buf_init because the circular buffer holds size-1 elements.
  I updated the document in the header accordingly.
• It simplifies circular_buf_empty by removing a pointless test of whether the buffer is full.
  That test is only needed in the "use a separate full flag to disambiguate full vs empty" version,
  as explained in your documentation: https://embeddedartistry.com/blog/2017/05/17/creating-a-circular-buffer-in-c-and-c/#circularbuffercontainertype

How Has This Been Tested?

Please describe the tests that you ran to verify your changes. Please also note any relevant details for your test configuration.

I didn't test the changes because I could not find the unit tests. I may well have just missed them, but I doubt I could have run them anyway because...

My attempt to build the package failed in ways that do not appear to have anything to do with my changes.
I am hoping somebody else will be willing to try to build it.
(We are using a bit of the source code, but not the build system.)

Here is a log:

% make
[54/137] Compiling C++ object examples/cpp/libdispatch_threadx_stdmutex.a.p/dispatch_threadx_stdmutex.cpp.o
FAILED: examples/cpp/libdispatch_threadx_stdmutex.a.p/dispatch_threadx_stdmutex.cpp.o 
clang++ -Iexamples/cpp/libdispatch_threadx_stdmutex.a.p -Iexamples/cpp -I../examples/cpp -I../examples/rtos -Iexamples/libcpp -I../examples/libcpp -fcolor-diagnostics -Wall -Winvalid-pch -Wnon-virtual-dtor -std=c++17 -g -Wno-unknown-pragmas -fno-rtti -fno-exceptions -fno-unwind-tables -DTHREADX=1 -D_LIBCPP_NO_EXCEPTIONS -DTHREADING=1 -D_LIBCPP_HAS_THREAD_API_EXTERNAL -fno-builtin -static -nodefaultlibs -MD -MQ examples/cpp/libdispatch_threadx_stdmutex.a.p/dispatch_threadx_stdmutex.cpp.o -MF examples/cpp/libdispatch_threadx_stdmutex.a.p/dispatch_threadx_stdmutex.cpp.o.d -o examples/cpp/libdispatch_threadx_stdmutex.a.p/dispatch_threadx_stdmutex.cpp.o -c ../examples/cpp/dispatch_threadx_stdmutex.cpp
In file included from ../examples/cpp/dispatch_threadx_stdmutex.cpp:1:
In file included from /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include/c++/v1/functional:504:
In file included from /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include/c++/v1/memory:681:
/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include/c++/v1/atomic:1537:12: error: use of undeclared identifier '__libcpp_thread_poll_with_backoff'
    return __libcpp_thread_poll_with_backoff(__test_fn, __backoff_fn);
           ^
/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include/c++/v1/atomic:1570:12: note: in instantiation of function template specialization 'std::__1::__cxx_atomic_wait<const volatile std::__1::__cxx_atomic_impl<bool>, std::__1::__cxx_atomic_wait_test_fn_impl<const volatile std::__1::__cxx_atomic_impl<bool>, bool> &>' requested here
    return __cxx_atomic_wait(__a, __test_fn);
           ^
/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include/c++/v1/atomic:2512:10: note: in instantiation of function template specialization 'std::__1::__cxx_atomic_wait<const volatile std::__1::__cxx_atomic_impl<bool>, bool>' requested here
        {__cxx_atomic_wait(&__a_, _LIBCPP_ATOMIC_FLAG_TYPE(__v), __m);}
         ^
/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include/c++/v1/atomic:1537:12: error: use of undeclared identifier '__libcpp_thread_poll_with_backoff'
    return __libcpp_thread_poll_with_backoff(__test_fn, __backoff_fn);
           ^
/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include/c++/v1/atomic:1570:12: note: in instantiation of function template specialization 'std::__1::__cxx_atomic_wait<const std::__1::__cxx_atomic_impl<bool>, std::__1::__cxx_atomic_wait_test_fn_impl<const std::__1::__cxx_atomic_impl<bool>, bool> &>' requested here
    return __cxx_atomic_wait(__a, __test_fn);
           ^
/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include/c++/v1/atomic:2515:10: note: in instantiation of function template specialization 'std::__1::__cxx_atomic_wait<const std::__1::__cxx_atomic_impl<bool>, bool>' requested here
        {__cxx_atomic_wait(&__a_, _LIBCPP_ATOMIC_FLAG_TYPE(__v), __m);}
         ^
2 errors generated.
ninja: build stopped: subcommand failed.
make: *** [examples] Error 1

Checklist:

• [ x] My code follows the style guidelines of this project
• [x ] I have performed a self-review of my own code
• [x ] I have commented my code, particularly in hard-to-understand areas
• [x ] I have made corresponding changes to the documentation
• My changes generate no new warnings
• [x ] Any dependent changes have been merged and published in downstream modules

[phillipjohnston]

Fantastic catch!

[phillipjohnston]

Thank you very much for these changes. It does build a program that runs a quick set of tests, but you are correct that there is no separate test program registered. Probably good for me to put some unit testing in place.

Regarding the failure - can you share your MacOS version and XCode version with me in #40 so I can get it figured out?