Add request example with future

examples/CMakeLists.txt

@@ -48,3 +48,14 @@ target_compile_options(ozo_connection_pool PRIVATE -Wall -Wextra -Wsign-compare
 if ("${CMAKE_CXX_COMPILER_ID}" STREQUAL "Clang")
     target_compile_options(ozo_connection_pool PRIVATE -Wno-ignored-optimization-argument)
 endif()
+
+add_executable(ozo_request_future request_future.cpp)
+target_link_libraries(ozo_request_future ozo)
+
+# enable a bunch of warnings and make them errors
+target_compile_options(ozo_request_future PRIVATE -Wall -Wextra -Wsign-compare -pedantic -Werror)
+
+# ignore specific errors for clang
+if ("${CMAKE_CXX_COMPILER_ID}" STREQUAL "Clang")
+    target_compile_options(ozo_request_future PRIVATE -Wno-ignored-optimization-argument)
+endif()

examples/request_future.cpp

@@ -0,0 +1,75 @@
+#include <ozo/connection_info.h>
+#include <ozo/request.h>
+#include <ozo/shortcuts.h>
+
+#include <boost/asio/io_service.hpp>
+#include <boost/asio/use_future.hpp>
+
+#include <iostream>
+#include <thread>
+
+namespace asio = boost::asio;
+
+int main(int argc, char **argv) {
+    std::cout << "OZO request example" << std::endl;
+
+    if (argc < 2) {
+        std::cerr << "Usage: " << argv[0] << " <connection string>\n";
+        return 1;
+    }
+
+    // Ozo perform all IO using Boost.Asio, so first thing we need to do is setup asio::io_context
+    asio::io_context io;
+
+    // To make a request we need to make a ConnectionSource. It knows how to connect to database using
+    // connection string. See https://www.postgresql.org/docs/9.4/static/libpq-connect.html#LIBPQ-CONNSTRING
+    // how to make a connection string.
+    auto conn_info = ozo::connection_info(argv[1]);
+
+    // All IO is asynchronous, therefore we have a choice here, what should be our CompletionToken.
+    // We use boost::asio::use_future. To make this example more real all asynchronous operation will be performed
+    // in a separate thread. Work guard will help to keep io_context running until we decide to stop it.
+    boost::asio::executor_work_guard<boost::asio::io_context::executor_type> guard = boost::asio::make_work_guard(io);
+    std::thread worker([&io] {
+        io.run();
+    });
+
+    // Request result is always set of rows. Client should take care of output object lifetime.
+    ozo::rows_of<int> result;
+
+    // Request operation require ConnectionProvider, query, output object for result and CompletionToken.
+    // Also we setup request timeout and reference for error code to avoid throwing exceptions.
+    // Function returns connection which can be used as ConnectionProvider for futher requests or to
+    // get additional information about error through error context.
+    ozo::error_code ec;
+
+    // This allows to use _SQL literals
+    using namespace ozo::literals;
+    using namespace std::chrono_literals;
+    auto connection = ozo::request(conn_info[io], "SELECT 1"_SQL, 1s, ozo::into(result), asio::use_future);
+
+    // When request is completed we check is there an exception. This example should not produce any errors
+    // if there are no problems with target database, network or permissions for given user in connection
+    // string.
+    try {
+        // Here we wait until asynchronous operation in a different thread is finished. If any error is occured
+        // an exception will be thrown. Unfortunately without any additional context, only static error code message.
+        connection.get();
+
+        // Just print request result
+        std::cout << "Selected:" << std::endl;
+        for (auto value : result) {
+            std::cout << std::get<0>(value) << std::endl;
+        }
+    } catch (const std::exception& error) {
+        std::cout << "Request failed with error: " << error.what();
+    }
+
+    // Reset work guard to release io and make it able to stop.
+    guard.reset();
+
+    // Make sure thread is finished.
+    worker.join();
+
+    return 0;
+}

scripts/run_example.sh

@@ -19,6 +19,7 @@ run_example ozo_request_coroutine
 run_example ozo_connection_pool
 run_example ozo_retry_request
 run_example ozo_role_based_request
+run_example ozo_request_future
 
 docker-compose stop ozo_postgres
 docker-compose rm -f ozo_postgres