Added some [[nodiscard]], coro lifetime attributes

- Added [[nodiscard]] to Coroutine, Error, Result, etc.
- static_ASYNC, virtual_ASYNC macros no longer necessary
- Added coro_return_type_ etc. but they aren't implemented in the
  version of Clang in Xcode 16

include/crouton/CoCondition.hh

@@ -94,7 +94,7 @@ namespace crouton {
 
         Blocker supports only one waiting coroutine. If you need more, use a CoCondition. */
     template <typename T>
-    class Blocker : public BlockerBase {
+    class [[nodiscard]] Blocker : public BlockerBase {
     public:
         T await_resume() noexcept {
             assert(_state == Ready);
@@ -116,7 +116,7 @@ namespace crouton {
 
 
     template <>
-    class Blocker<void> : public BlockerBase {
+    class [[nodiscard]] Blocker<void> : public BlockerBase {
     public:
         void notify()   {BlockerBase::notify();}
     };

include/crouton/Coroutine.hh

@@ -30,7 +30,7 @@ namespace crouton {
     /** Base class for the public object returned by a coroutine function.
         Most of the implementation is usually in the associated CoroutineImpl subclass (IMPL). */
     template <class IMPL>
-    class Coroutine {
+    class [[nodiscard]] coro_return_type_ Coroutine {
     public:
         // movable, but not copyable.
         Coroutine(Coroutine&& c) noexcept           :_handle(c._handle) {c._handle = {};}
@@ -94,7 +94,7 @@ namespace crouton {
 
 
 
-    class CoroutineImplBase {
+    class coro_wrapper_ CoroutineImplBase {
     public:
         CoroutineImplBase() = default;
         ~CoroutineImplBase();

include/crouton/CroutonFwd.hh

@@ -24,12 +24,8 @@
    To be #include'd in header files instead of Crouton.hh, when possible. */
 
 
-/// Macros for declaring a function that returns a Future, e.g. `ASYNC<void> close();`
-/// It's surprisingly easy to forget to await the Future, especially `Future<void>`,
-/// hence the `[[nodiscard]]` annotation.
-#define        ASYNC [[nodiscard("Future must be AWAITed or returned")]]         ::crouton::Future
-#define  staticASYNC [[nodiscard("Future must be AWAITed or returned")]] static  ::crouton::Future
-#define virtualASYNC [[nodiscard("Future must be AWAITed or returned")]] virtual ::crouton::Future
+/// Marker macro for declaring a function that returns a Future, e.g. `ASYNC<void> close();`
+#define ASYNC  ::crouton::Future
 
 
 namespace crouton {

include/crouton/Error.hh

@@ -65,7 +65,7 @@ namespace crouton {
 
     /** Error holds an error code as a type-erased enum value, of any type that matches `ErrorDomain`.
         There's also a default empty state. */
-    class Error {
+    class [[nodiscard("check for error")]] Error {
     public:
         /// The default no-error value. Available as the constant `noerror`.
         constexpr Error() = default;

include/crouton/EventLoop.hh

@@ -82,7 +82,7 @@ namespace crouton {
         static void after(double delaySecs, std::function<void()> fn);
 
         /// Static method that returns a Future that completes after the given delay.
-        staticASYNC<void> sleep(double delaySecs);
+        static ASYNC<void> sleep(double delaySecs);
 
     private:
         friend class EventLoop;

include/crouton/Future.hh

@@ -53,7 +53,8 @@ namespace crouton {
 
         A regular function that gets a Future can call `then()` to register a callback. */
     template <typename T>
-    class Future : public Coroutine<FutureImpl<T>>, public ISelectable {
+    class [[nodiscard("Future must be AWAITed or returned")]]
+    Future : public Coroutine<FutureImpl<T>>, public ISelectable {
     public:
         using nonvoidT = std::conditional_t<std::is_void_v<T>, std::byte, T>;
 

include/crouton/Generator.hh

@@ -42,7 +42,7 @@ namespace crouton {
         A Generator can also be iterated synchronously via its begin/end methods,
         or with a `for(:)` loop.*/
     template <typename T>
-    class Generator : public Coroutine<GeneratorImpl<T>>, public ISeries<T> {
+    class [[nodiscard]] Generator : public Coroutine<GeneratorImpl<T>>, public ISeries<T> {
     public:
         Generator(Generator&&) noexcept = default;
         Generator& operator=(Generator&&) = default;

include/crouton/PubSub.hh

@@ -138,7 +138,7 @@ namespace crouton::ps {
 
         /// Abstract method that handles an item received from the Publisher.
         /// @warning  You must override either this method or `run`.
-        virtualASYNC<void> handle(T)            {return CroutonError::Unimplemented;}
+        virtual ASYNC<void> handle(T)            {return CroutonError::Unimplemented;}
 
         /// Handles the final Error/noerror item from the publisher.
         /// Default implementation sets the `error` property; make sure to call through.

include/crouton/Result.hh

@@ -28,7 +28,7 @@ namespace crouton {
         (A `Result<void>` has no explicit value, but still distinguishes between empty/nonempty.)
         It's commonly used as a return type, and in the implementation of `Future<T>`. */
     template <typename T>
-    class Result {
+    class [[nodiscard("check Result for error")]] Result {
     public:
         using TT = std::conditional_t<std::is_void_v<T>, std::monostate, T>;
 

include/crouton/Scheduler.hh

@@ -99,7 +99,7 @@ namespace crouton {
 
         //==== Awaitable:
 
-        class SchedAwaiter  {
+        class SchedAwaiter {
         public:
             explicit SchedAwaiter(Scheduler* sched)     :_sched(sched) { }
             bool await_ready() noexcept                 {return _sched->isCurrent();}
@@ -138,12 +138,12 @@ namespace crouton {
         void resumed(coro_handle h);
 
         /// Returns the coroutine that should be resumed, or else `dflt`.
-        coro_handle nextOr(coro_handle dflt);
+        [[nodiscard]] coro_handle nextOr(coro_handle dflt);
 
         /// Adds a coroutine handle to the suspension set.
         /// To make it runnable again, call the returned Suspension's `wakeUp` method
         /// from any thread.
-        Suspension suspend(coro_handle h);
+        [[nodiscard]] Suspension suspend(coro_handle h);
 
         /// Tells the Scheduler a coroutine is about to be destroyed, so it can manage it
         /// correctly if it's in the suspended set.

include/crouton/io/AddrInfo.hh

@@ -38,7 +38,7 @@ namespace crouton::io {
 #endif
 
         /// Does a DNS lookup of the given hostname, returning an AddrInfo or an error.
-        staticASYNC<AddrInfo> lookup(string hostname, uint16_t port =0);
+        static ASYNC<AddrInfo> lookup(string hostname, uint16_t port =0);
 
         /// Returns the primary address, which may be either IPv4 or IPv6.
         RawAddress const& primaryAddress() const;

include/crouton/io/FileStream.hh

@@ -60,7 +60,7 @@ namespace crouton::io {
 
         ASYNC<ConstBytes> readNoCopy(size_t maxLen = 65536) override;
         ASYNC<ConstBytes> peekNoCopy() override;
-        virtualASYNC<string> readAll() override;
+        virtual ASYNC<string> readAll() override;
 
         ASYNC<void> write(ConstBytes) override;
         ASYNC<void> write(const ConstBytes buffers[], size_t nBuffers) override;

include/crouton/io/ISocket.hh

@@ -48,18 +48,18 @@ namespace crouton::io {
         virtual void keepAlive(unsigned intervalSecs)   {_binding->keepAlive = intervalSecs;}
 
         /// Opens the socket to the bound address. Resolves once opened.
-        virtualASYNC<void> open() =0;
+        virtual ASYNC<void> open() =0;
 
         /// Equivalent to bind + open.
-        virtualASYNC<void> connect(string const& address, uint16_t port);
+        virtual ASYNC<void> connect(string const& address, uint16_t port);
 
         /// True if the socket is open/connected.
         virtual bool isOpen() const =0;
 
         /// The socket's data stream.
         virtual std::shared_ptr<IStream> stream() =0;
 
-        virtualASYNC<void> close() =0;
+        virtual ASYNC<void> close() =0;
 
         virtual ~ISocket() = default;
 

include/crouton/io/IStream.hh

@@ -38,13 +38,13 @@ namespace crouton::io {
         virtual bool isOpen() const =0;
 
         /// Opens the stream, if it wasn't already open; resolves when it's open.
-        virtualASYNC<void> open() =0;
+        virtual ASYNC<void> open() =0;
 
         /// Closes the stream; resolves when it's closed.
-        virtualASYNC<void> close() =0;
+        virtual ASYNC<void> close() =0;
 
         /// Closes the write side, but not the read side. (Like a socket's `shutdown`.)
-        virtualASYNC<void> closeWrite() =0;
+        virtual ASYNC<void> closeWrite() =0;
 
         //---- Reading:
 
@@ -53,7 +53,7 @@ namespace crouton::io {
         /// @warning The returned buffer belongs to the stream, and is only valid until the next
         ///          read or close call.
         /// @note This is an abstract method that subclasses must implement.
-        virtualASYNC<ConstBytes> readNoCopy(size_t maxLen = 65536) =0;
+        virtual ASYNC<ConstBytes> readNoCopy(size_t maxLen = 65536) =0;
 
         /// Returns the next available unread bytes, always at least 1 byte except at EOF.
         /// Unlike `readNoCopy`, the returned bytes are _not consumed_ -- they will
@@ -62,11 +62,11 @@ namespace crouton::io {
         /// @warning The returned buffer belongs to the stream, and is only valid until the next
         ///          read or close call.
         /// @note This is an abstract method that subclasses must implement.
-        virtualASYNC<ConstBytes> peekNoCopy() =0;
+        virtual ASYNC<ConstBytes> peekNoCopy() =0;
 
         /// Reads `len` bytes, copying into memory starting at `dst` (which must remain valid.)
         /// Will always read the full number of bytes unless it hits EOF.
-        virtualASYNC<size_t> read(MutableBytes buf);
+        virtual ASYNC<size_t> read(MutableBytes buf);
 
         /// Reads `len` bytes, returning them as a string.
         /// Will always read the full number of bytes unless it hits EOF.
@@ -81,7 +81,7 @@ namespace crouton::io {
         ASYNC<string> readUntil(string end, size_t maxLen = SIZE_MAX);
 
         /// Reads until EOF.
-        virtualASYNC<string> readAll();
+        virtual ASYNC<string> readAll();
 
         /// Returns a `Generator` that produces chunks of data read from the stream.
         /// This is a wrapper around `readNoCopy()` that makes `IStream` satisfy the concept
@@ -94,7 +94,7 @@ namespace crouton::io {
         /// Writes all the bytes.
         /// @warning The memory must remain valid until this call completes.
         /// @note This is the abstract write method that subclasses must implement.
-        virtualASYNC<void> write(ConstBytes) =0;
+        virtual ASYNC<void> write(ConstBytes) =0;
 
         /// Writes data, fully. The string is copied, so the caller doesn't need to keep it.
         ASYNC<void> write(string);
@@ -104,7 +104,7 @@ namespace crouton::io {
         /// @note  The default implementation makes `nBuffers` calls to `write(ConstBytes)`.
         ///        A subclass that natively supports multi-buffer write ("writev") may override
         ///        this method as an optimization.
-        virtualASYNC<void> write(const ConstBytes buffers[], size_t nBuffers);
+        virtual ASYNC<void> write(const ConstBytes buffers[], size_t nBuffers);
 
         ASYNC<void> write(std::initializer_list<ConstBytes> buffers);
     };

include/crouton/io/Stream.hh

@@ -36,8 +36,8 @@ namespace crouton::io {
         /// Closes the write stream, leaving the read stream open until the peer closes it.
         ASYNC<void> closeWrite() override;
 
-        /// Closes the stream entirely. (Called by the destructor.)
-        virtual Future<void> close() override;
+        /// Closes the stream entirely.
+        virtual ASYNC<void> close() override;
 
         //---- READING
 

include/crouton/io/apple/NWConnection.hh

@@ -46,7 +46,7 @@ namespace crouton::io::apple {
         void useTLS(bool tls)                               {_useTLS = tls;}
 
         /// Opens the socket to the bound address. Resolves once opened.
-        virtualASYNC<void> open() override;
+        virtual ASYNC<void> open() override;
 
         bool isOpen() const override                        {return _isOpen;}
 
@@ -60,12 +60,12 @@ namespace crouton::io::apple {
         ~NWConnection();
 
     private:
-        virtualASYNC<ConstBytes> readNoCopy(size_t maxLen = 65536) override;
-        virtualASYNC<ConstBytes> peekNoCopy() override;
+        virtual ASYNC<ConstBytes> readNoCopy(size_t maxLen = 65536) override;
+        virtual ASYNC<ConstBytes> peekNoCopy() override;
         ASYNC<void> write(ConstBytes b) override;
         using IStream::write;
 
-        virtualASYNC<ConstBytes> _readNoCopy(size_t maxLen, bool peek);
+        virtual ASYNC<ConstBytes> _readNoCopy(size_t maxLen, bool peek);
         ASYNC<void> _writeOrShutdown(ConstBytes, bool shutdown);
         void _close();
         void clearReadBuf();

include/crouton/util/Base.hh

@@ -70,6 +70,30 @@
 #endif
 
 
+// These will be helpful for detecting bugs, but AppleClang doesn't support them yet as of Xcode 16.
+// <https://clang.llvm.org/docs/AttributeReference.html#id488>
+#if __has_attribute(coro_return_type)
+#   define coro_return_type_ [[clang::coro_return_type]]
+#else
+#   define coro_return_type_
+#endif
+#if __has_attribute(coro_wrapper)
+#   define coro_wrapper_ [[clang::coro_wrapper]]
+#else
+#   define coro_wrapper_
+#endif
+#if __has_attribute(coro_lifetimebound)
+#   define coro_lifetimebound_ [[clang::coro_lifetimebound]]
+#else
+#   define coro_lifetimebound_
+#endif
+#if __has_attribute(coro_disable_lifetimebound)
+#   define coro_disable_lifetimebound_ [[clang::coro_disable_lifetimebound]]
+#else
+#   define coro_disable_lifetimebound_
+#endif
+
+
 // Synonyms for coroutine primitives. Optional, but they're more visible in the code.
 #define AWAIT  co_await
 #define YIELD  co_yield

src/io/blip/Connection.cc

@@ -84,11 +84,11 @@ namespace crouton::io::blip {
         else
             _io.closeSend();
         auto& j = _outputTask->join();
-        AWAIT j;
+        (void) AWAIT j;
         LBLIP->debug("Connection now sending WebSocket CLOSE...");
         AWAIT _socket->send(ws::Message{code, message});
         auto& j2 = _inputTask->join();
-        AWAIT j2;
+        (void) AWAIT j2;
         AWAIT _socket->close();
         RETURN noerror;
     }

src/io/uv/Stream.cc

@@ -30,7 +30,7 @@ namespace crouton::io {
     Stream::Stream() = default;
 
     Stream::~Stream() {
-        close();
+        _close();
     }
 
 

src/support/Logging.cc

@@ -120,7 +120,7 @@ namespace crouton {
             assert_failed_hook = [](const char* message) {
                 Log->critical(message);
             };
-            Log->info("---------- Welcome to Crouton ----------");
+            //Log->info("---------- Welcome to Crouton ----------");
         });
     }
 

tests/ESP32/main/test_esp32.cc

@@ -73,7 +73,7 @@ static void testCodec() {
 }
 
 
-staticASYNC<void> testBLIP() {
+static ASYNC<void> testBLIP() {
     // Send HTTP request:
     auto ws = make_unique<ws::ClientWebSocket>("ws://work.local:4985/travel-sample/_blipsync");
     ws->setHeader("Sec-WebSocket-Protocol", "BLIP_3+CBMobile_2");
@@ -235,5 +235,3 @@ static void initialize() {
     esp_log_level_set("example_common", ESP_LOG_WARN);
     ESP_ERROR_CHECK(example_connect());
 }
-
-

tests/demo_blipclient.cc

@@ -28,13 +28,13 @@ using namespace crouton::mini;
 /* NOTE to newbies: this file uses some simple/optional macros that are used everywhere in Crouton
    to highlight suspend points and use of asynchronous code:
 
-    staticASYNC     --> [[nodiscard]] static Future
+    static ASYNC     --> [[nodiscard]] static Future
     AWAIT           --> co_await
     RETURN          --> co_return
 */
 
 
-staticASYNC<int> run() {
+static ASYNC<int> run() {
     // Read flags:
     auto args = MainArgs();
     string protocol;

tests/demo_client.cc

@@ -26,13 +26,13 @@ using namespace crouton::io;
 /* NOTE to newbies: this file uses some simple/optional macros that are used everywhere in Crouton
    to highlight suspend points and use of asynchronous code:
 
-    staticASYNC     --> [[nodiscard]] static Future
+    static ASYNC     --> [[nodiscard]] static Future
     AWAIT           --> co_await
     RETURN          --> co_return
 */
 
 
-staticASYNC<int> run() {
+static ASYNC<int> run() {
     // Read flags:
     auto args = MainArgs();
     bool includeHeaders = false;