Mark default loop init with nodiscard

docs/how-to/communicate.example.c

@@ -72,8 +72,13 @@ int main(int argc, char const* const* argv) {
     }
     const char* const uri = argv[1];
 
-    amongoc_loop loop;
-    amongoc_default_loop_init(&loop);
+    amongoc_loop   loop;
+    amongoc_status status = amongoc_default_loop_init(&loop);
+    if (amongoc_is_error(status)) {
+        amongoc_declmsg(msg, status);
+        fprintf(stderr, "Error setting up the event loop: %s\n", msg);
+        return 2;
+    }
 
     struct app_state state = {0};
 
@@ -88,8 +93,7 @@ int main(int argc, char const* const* argv) {
                      amongoc_box_pointer(&state),
                      after_connect_say_hello);
 
-    amongoc_status    fin_status = amongoc_okay;
-    amongoc_operation op         = amongoc_tie(em, &fin_status);
+    amongoc_operation op = amongoc_tie(em, &status);
     amongoc_start(&op);
     amongoc_default_loop_run(&loop);
     amongoc_operation_delete(op);
@@ -98,8 +102,8 @@ int main(int argc, char const* const* argv) {
     amongoc_client_delete(state.client);
     amongoc_default_loop_destroy(&loop);
 
-    if (amongoc_is_error(fin_status)) {
-        amongoc_declmsg(msg, fin_status);
+    if (amongoc_is_error(status)) {
+        amongoc_declmsg(msg, status);
         fprintf(stderr, "An error occurred: %s\n", msg);
         return 2;
     } else {

docs/how-to/communicate.rst

@@ -46,7 +46,7 @@ The first "interesting" code will declare and initialize the default event loop:
 .. literalinclude:: communicate.example.c
   :lineno-match:
   :start-at: loop;
-  :end-at: );
+  :end-at: }
 
 .. seealso:: `amongoc_loop` and `amongoc_default_loop_init`
 
@@ -204,7 +204,7 @@ the first continuation, we use `amongoc_tie` to convert the emitter to an
 
 .. literalinclude:: communicate.example.c
   :lineno-match:
-  :start-at: fin_status
+  :start-at: amongoc_tie
   :end-at: amongoc_tie
 
 This will allow us to see the final result status of the program in

docs/learn/connect.example.c

@@ -7,8 +7,13 @@
 amongoc_box on_connect(amongoc_box userdata, amongoc_status* status, amongoc_box result);
 
 int main(void) {
-    amongoc_loop loop;
-    amongoc_default_loop_init(&loop);
+    amongoc_loop   loop;
+    amongoc_status status = amongoc_default_loop_init(&loop);
+    if (amongoc_is_error(status)) {
+        amongoc_declmsg(msg, status);
+        fprintf(stderr, "Failed to prepare the event loop: %s\n", msg);
+        return 2;
+    }
 
     // Initiate a connection
     amongoc_emitter em = amongoc_client_new(&loop, "mongodb://localhost:27017");

docs/learn/connect.rst

@@ -29,7 +29,7 @@ programs:
 .. literalinclude:: connect.example.c
   :caption: Create a default event loop
   :start-at: int main
-  :end-at: default_loop_init
+  :end-at: }
   :lineno-match:
   :dedent:
 

include/amongoc/default_loop.h

@@ -8,9 +8,11 @@
 
 mlib_extern_c_begin();
 
-extern amongoc_status        amongoc_default_loop_init_with_allocator(amongoc_loop* loop,
-                                                                      mlib_allocator) mlib_noexcept;
-static inline amongoc_status amongoc_default_loop_init(amongoc_loop* loop) mlib_noexcept {
+mlib_nodiscard("This function may fail to allocate resources") extern amongoc_status
+    amongoc_default_loop_init_with_allocator(amongoc_loop* loop, mlib_allocator) mlib_noexcept;
+
+mlib_nodiscard("This function may fail to allocate resources") static inline amongoc_status
+    amongoc_default_loop_init(amongoc_loop* loop) mlib_noexcept {
     return amongoc_default_loop_init_with_allocator(loop, mlib_default_allocator);
 }
 
@@ -24,7 +26,7 @@ namespace amongoc {
 
 struct default_event_loop {
 public:
-    default_event_loop() { ::amongoc_default_loop_init(&_loop); }
+    default_event_loop() { ::amongoc_default_loop_init(&_loop).throw_for_error(); }
     ~default_event_loop() { ::amongoc_default_loop_destroy(&_loop); }
 
     default_event_loop(default_event_loop&&) = delete;

include/amongoc/status.h

@@ -797,6 +797,8 @@ struct amongoc_status {
     constexpr bool operator!=(amongoc_status const& other) const noexcept {
         return not(*this == other);
     }
+
+    inline void throw_for_error() const;
 #endif
 };
 
@@ -895,4 +897,9 @@ class exception : std::runtime_error {
 
 bool amongoc_status::is_error() const noexcept { return amongoc_is_error(*this); }
 
+void amongoc_status::throw_for_error() const {
+    if (this->is_error()) {
+        throw amongoc::exception(*this);
+    }
+}
 #endif

src/amongoc/async.test.cpp

@@ -45,7 +45,7 @@ TEST_CASE("Async/Transform with the C API") {
 
 TEST_CASE("Async/Timeout") {
     amongoc_loop loop;
-    amongoc_default_loop_init(&loop);
+    amongoc_default_loop_init(&loop).throw_for_error();
     // One minute delay (too slow)
     auto dur          = timespec{};
     dur.tv_sec        = 60;
@@ -93,7 +93,7 @@ emitter waits(amongoc_loop& loop) {
 
 TEST_CASE("Async/let") {
     amongoc_loop loop;
-    amongoc_default_loop_init(&loop);
+    amongoc_default_loop_init(&loop).throw_for_error();
     auto em = amongoc_let(waits(loop),
                           amongoc_async_forward_errors,
                           mlib_default_allocator,