Merge pull request #79 from taocpp/log

Log handler infrastructure, more log callbacks will be added in the future.

.clang-format

@@ -1,7 +1,7 @@
 # The Art of C++
 # https://github.com/taocpp
 
-# Copyright (c) 2016-2024 Dr. Colin Hirsch and Daniel Frey
+# Copyright (c) 2016-2025 Dr. Colin Hirsch and Daniel Frey
 # Distributed under the Boost Software License, Version 1.0.
 # (See accompanying file LICENSE_1_0.txt or copy at https://www.boost.org/LICENSE_1_0.txt)
 

.clang-tidy

@@ -1,7 +1,7 @@
 # The Art of C++
 # https://github.com/taocpp
 
-# Copyright (c) 2016-2024 Dr. Colin Hirsch and Daniel Frey
+# Copyright (c) 2016-2025 Dr. Colin Hirsch and Daniel Frey
 # Distributed under the Boost Software License, Version 1.0.
 # (See accompanying file LICENSE_1_0.txt or copy at https://www.boost.org/LICENSE_1_0.txt)
 

CMakeLists.txt

@@ -30,6 +30,7 @@ set(taopq_INCLUDE_FILES
   ${taopq_INCLUDE_DIRS}/tao/pq/internal/aggregate.hpp
   ${taopq_INCLUDE_DIRS}/tao/pq/internal/demangle.hpp
   ${taopq_INCLUDE_DIRS}/tao/pq/internal/exclusive_scan.hpp
+  ${taopq_INCLUDE_DIRS}/tao/pq/internal/format_as.hpp
   ${taopq_INCLUDE_DIRS}/tao/pq/internal/from_chars.hpp
   ${taopq_INCLUDE_DIRS}/tao/pq/internal/gen.hpp
   ${taopq_INCLUDE_DIRS}/tao/pq/internal/parameter_traits_helper.hpp
@@ -43,6 +44,7 @@ set(taopq_INCLUDE_FILES
   ${taopq_INCLUDE_DIRS}/tao/pq/is_array.hpp
   ${taopq_INCLUDE_DIRS}/tao/pq/isolation_level.hpp
   ${taopq_INCLUDE_DIRS}/tao/pq/large_object.hpp
+  ${taopq_INCLUDE_DIRS}/tao/pq/log.hpp
   ${taopq_INCLUDE_DIRS}/tao/pq/notification.hpp
   ${taopq_INCLUDE_DIRS}/tao/pq/null.hpp
   ${taopq_INCLUDE_DIRS}/tao/pq/oid.hpp

Makefile

@@ -1,7 +1,7 @@
 # The Art of C++
 # https://github.com/taocpp
 
-# Copyright (c) 2016-2024 Daniel Frey
+# Copyright (c) 2016-2025 Daniel Frey
 # Distributed under the Boost Software License, Version 1.0.
 # (See accompanying file LICENSE_1_0.txt or copy at https://www.boost.org/LICENSE_1_0.txt)
 

README.md

@@ -85,7 +85,7 @@ taoPQ is part of [The Art of C++](https://taocpp.github.io/).
 
 <a href="https://opensource.org/licenses/BSL-1.0"><img align="right" src="https://opensource.org/wp-content/uploads/2009/06/OSIApproved.svg" width="150" hspace="20" alt="Open Source Initiative"></a>
 
-Copyright (c) 2016-2024 Daniel Frey and Dr. Colin Hirsch
+Copyright (c) 2016-2025 Daniel Frey and Dr. Colin Hirsch
 
 taoPQ is certified [Open Source➚](http://www.opensource.org/docs/definition.html) software.
 It is [licensed➚](https://pdimov.github.io/blog/2020/09/06/why-use-the-boost-license/) under the terms of the [Boost Software License, Version 1.0➚](https://www.boost.org/LICENSE_1_0.txt) reproduced here.

doc/Aggregate-Support.md

@@ -94,6 +94,6 @@ int main()
 
 This document is part of [taoPQ](https://github.com/taocpp/taopq).
 
-Copyright (c) 2021-2024 Daniel Frey and Dr. Colin Hirsch<br>
+Copyright (c) 2021-2025 Daniel Frey and Dr. Colin Hirsch<br>
 Distributed under the Boost Software License, Version 1.0<br>
 See accompanying file [LICENSE_1_0.txt](../LICENSE_1_0.txt) or copy at https://www.boost.org/LICENSE_1_0.txt

doc/Binary-Data.md

@@ -53,6 +53,6 @@ In some cases other alternatives are offered, i.e. you may provide a buffer that
 
 This document is part of [taoPQ](https://github.com/taocpp/taopq).
 
-Copyright (c) 2021-2024 Daniel Frey and Dr. Colin Hirsch<br>
+Copyright (c) 2021-2025 Daniel Frey and Dr. Colin Hirsch<br>
 Distributed under the Boost Software License, Version 1.0<br>
 See accompanying file [LICENSE_1_0.txt](../LICENSE_1_0.txt) or copy at https://www.boost.org/LICENSE_1_0.txt

doc/Bulk-Transfer.md

@@ -248,6 +248,6 @@ namespace tao::pq
 
 This document is part of [taoPQ](https://github.com/taocpp/taopq).
 
-Copyright (c) 2021-2024 Daniel Frey and Dr. Colin Hirsch<br>
+Copyright (c) 2021-2025 Daniel Frey and Dr. Colin Hirsch<br>
 Distributed under the Boost Software License, Version 1.0<br>
 See accompanying file [LICENSE_1_0.txt](../LICENSE_1_0.txt) or copy at https://www.boost.org/LICENSE_1_0.txt

doc/Connection-Pool.md

@@ -178,6 +178,6 @@ We minimized the work in the [critical sections➚](https://en.wikipedia.org/wik
 
 This document is part of [taoPQ](https://github.com/taocpp/taopq).
 
-Copyright (c) 2021-2024 Daniel Frey and Dr. Colin Hirsch<br>
+Copyright (c) 2021-2025 Daniel Frey and Dr. Colin Hirsch<br>
 Distributed under the Boost Software License, Version 1.0<br>
 See accompanying file [LICENSE_1_0.txt](../LICENSE_1_0.txt) or copy at https://www.boost.org/LICENSE_1_0.txt

doc/Connection.md

@@ -411,6 +411,6 @@ When taoPQ throws an exception this is usually done internally and the message i
 
 This document is part of [taoPQ](https://github.com/taocpp/taopq).
 
-Copyright (c) 2021-2024 Daniel Frey and Dr. Colin Hirsch<br>
+Copyright (c) 2021-2025 Daniel Frey and Dr. Colin Hirsch<br>
 Distributed under the Boost Software License, Version 1.0<br>
 See accompanying file [LICENSE_1_0.txt](../LICENSE_1_0.txt) or copy at https://www.boost.org/LICENSE_1_0.txt

doc/Error-Handling.md

@@ -78,6 +78,6 @@ The same exception can also be thrown when calling the connection's `get_notific
 
 This document is part of [taoPQ](https://github.com/taocpp/taopq).
 
-Copyright (c) 2021-2024 Daniel Frey and Dr. Colin Hirsch<br>
+Copyright (c) 2021-2025 Daniel Frey and Dr. Colin Hirsch<br>
 Distributed under the Boost Software License, Version 1.0<br>
 See accompanying file [LICENSE_1_0.txt](../LICENSE_1_0.txt) or copy at https://www.boost.org/LICENSE_1_0.txt

doc/Getting-Started.md

@@ -67,6 +67,6 @@ The following chapters are good next steps to get to know taoPQ:
 
 This document is part of [taoPQ](https://github.com/taocpp/taopq).
 
-Copyright (c) 2021-2024 Daniel Frey and Dr. Colin Hirsch<br>
+Copyright (c) 2021-2025 Daniel Frey and Dr. Colin Hirsch<br>
 Distributed under the Boost Software License, Version 1.0<br>
 See accompanying file [LICENSE_1_0.txt](../LICENSE_1_0.txt) or copy at https://www.boost.org/LICENSE_1_0.txt

doc/Installation.md

@@ -40,6 +40,6 @@ When executing the build step, taoPQ will be built first, as its target is requi
 
 This document is part of [taoPQ](https://github.com/taocpp/taopq).
 
-Copyright (c) 2021-2024 Daniel Frey and Dr. Colin Hirsch<br>
+Copyright (c) 2021-2025 Daniel Frey and Dr. Colin Hirsch<br>
 Distributed under the Boost Software License, Version 1.0<br>
 See accompanying file [LICENSE_1_0.txt](../LICENSE_1_0.txt) or copy at https://www.boost.org/LICENSE_1_0.txt

doc/Large-Object.md

@@ -222,6 +222,6 @@ If an error occurs an exception will be thrown.
 
 This document is part of [taoPQ](https://github.com/taocpp/taopq).
 
-Copyright (c) 2021-2024 Daniel Frey and Dr. Colin Hirsch<br>
+Copyright (c) 2021-2025 Daniel Frey and Dr. Colin Hirsch<br>
 Distributed under the Boost Software License, Version 1.0<br>
 See accompanying file [LICENSE_1_0.txt](../LICENSE_1_0.txt) or copy at https://www.boost.org/LICENSE_1_0.txt

doc/Parameter-Type-Conversion.md

@@ -186,6 +186,6 @@ TODO: Write proper documentation.
 
 This document is part of [taoPQ](https://github.com/taocpp/taopq).
 
-Copyright (c) 2021-2024 Daniel Frey and Dr. Colin Hirsch<br>
+Copyright (c) 2021-2025 Daniel Frey and Dr. Colin Hirsch<br>
 Distributed under the Boost Software License, Version 1.0<br>
 See accompanying file [LICENSE_1_0.txt](../LICENSE_1_0.txt) or copy at https://www.boost.org/LICENSE_1_0.txt

doc/Performance.md

@@ -6,6 +6,6 @@
 
 This document is part of [taoPQ](https://github.com/taocpp/taopq).
 
-Copyright (c) 2021-2024 Daniel Frey and Dr. Colin Hirsch<br>
+Copyright (c) 2021-2025 Daniel Frey and Dr. Colin Hirsch<br>
 Distributed under the Boost Software License, Version 1.0<br>
 See accompanying file [LICENSE_1_0.txt](../LICENSE_1_0.txt) or copy at https://www.boost.org/LICENSE_1_0.txt

doc/Requirements.md

@@ -42,6 +42,6 @@ You can decide which options you want to use in your project, we just try to not
 
 This document is part of [taoPQ](https://github.com/taocpp/taopq).
 
-Copyright (c) 2021-2024 Daniel Frey and Dr. Colin Hirsch<br>
+Copyright (c) 2021-2025 Daniel Frey and Dr. Colin Hirsch<br>
 Distributed under the Boost Software License, Version 1.0<br>
 See accompanying file [LICENSE_1_0.txt](../LICENSE_1_0.txt) or copy at https://www.boost.org/LICENSE_1_0.txt

doc/Result-Type-Conversion.md

@@ -146,6 +146,6 @@ TODO: Write proper documentation.
 
 This document is part of [taoPQ](https://github.com/taocpp/taopq).
 
-Copyright (c) 2021-2024 Daniel Frey and Dr. Colin Hirsch<br>
+Copyright (c) 2021-2025 Daniel Frey and Dr. Colin Hirsch<br>
 Distributed under the Boost Software License, Version 1.0<br>
 See accompanying file [LICENSE_1_0.txt](../LICENSE_1_0.txt) or copy at https://www.boost.org/LICENSE_1_0.txt

doc/Result.md

@@ -482,6 +482,6 @@ auto tao::pq::field::optional() const
 
 This document is part of [taoPQ](https://github.com/taocpp/taopq).
 
-Copyright (c) 2021-2024 Daniel Frey and Dr. Colin Hirsch<br>
+Copyright (c) 2021-2025 Daniel Frey and Dr. Colin Hirsch<br>
 Distributed under the Boost Software License, Version 1.0<br>
 See accompanying file [LICENSE_1_0.txt](../LICENSE_1_0.txt) or copy at https://www.boost.org/LICENSE_1_0.txt

doc/Statement.md

@@ -125,6 +125,6 @@ The [Parameter Type Conversion](Parameter-Type-Conversion.md) chapter explains w
 
 This document is part of [taoPQ](https://github.com/taocpp/taopq).
 
-Copyright (c) 2021-2024 Daniel Frey and Dr. Colin Hirsch<br>
+Copyright (c) 2021-2025 Daniel Frey and Dr. Colin Hirsch<br>
 Distributed under the Boost Software License, Version 1.0<br>
 See accompanying file [LICENSE_1_0.txt](../LICENSE_1_0.txt) or copy at https://www.boost.org/LICENSE_1_0.txt

doc/Transaction.md

@@ -160,6 +160,6 @@ auto tao::pq::transaction::connection() const noexcept
 
 This document is part of [taoPQ](https://github.com/taocpp/taopq).
 
-Copyright (c) 2021-2024 Daniel Frey and Dr. Colin Hirsch<br>
+Copyright (c) 2021-2025 Daniel Frey and Dr. Colin Hirsch<br>
 Distributed under the Boost Software License, Version 1.0<br>
 See accompanying file [LICENSE_1_0.txt](../LICENSE_1_0.txt) or copy at https://www.boost.org/LICENSE_1_0.txt

include/tao/pq.hpp

@@ -1,4 +1,4 @@
-// Copyright (c) 2016-2024 Daniel Frey and Dr. Colin Hirsch
+// Copyright (c) 2016-2025 Daniel Frey and Dr. Colin Hirsch
 // Distributed under the Boost Software License, Version 1.0.
 // (See accompanying file LICENSE_1_0.txt or copy at https://www.boost.org/LICENSE_1_0.txt)
 
@@ -27,6 +27,7 @@
 #include <tao/pq/parameter_traits_tuple.hpp>
 
 #include <tao/pq/exception.hpp>
+#include <tao/pq/log.hpp>
 #include <tao/pq/result.hpp>
 
 #include <tao/pq/result_traits.hpp>

include/tao/pq/access_mode.hpp

@@ -1,11 +1,14 @@
-// Copyright (c) 2021-2024 Daniel Frey and Dr. Colin Hirsch
+// Copyright (c) 2021-2025 Daniel Frey and Dr. Colin Hirsch
 // Distributed under the Boost Software License, Version 1.0.
 // (See accompanying file LICENSE_1_0.txt or copy at https://www.boost.org/LICENSE_1_0.txt)
 
 #ifndef TAO_PQ_ACCESS_MODE_HPP
 #define TAO_PQ_ACCESS_MODE_HPP
 
 #include <cstdint>
+#include <string_view>
+
+#include <tao/pq/internal/format_as.hpp>
 
 namespace tao::pq
 {
@@ -16,6 +19,23 @@ namespace tao::pq
       read_only
    };
 
+   [[nodiscard]] constexpr auto taopq_format_as( const access_mode am ) noexcept -> std::string_view
+   {
+      switch( am ) {
+         case access_mode::default_access_mode:
+            return "default_access_mode";
+
+         case access_mode::read_write:
+            return "read_write";
+
+         case access_mode::read_only:
+            return "read_only";
+
+         default:
+            return "<unknown>";
+      }
+   }
+
 }  // namespace tao::pq
 
 #endif

include/tao/pq/binary.hpp

@@ -1,4 +1,4 @@
-// Copyright (c) 2021-2024 Daniel Frey and Dr. Colin Hirsch
+// Copyright (c) 2021-2025 Daniel Frey and Dr. Colin Hirsch
 // Distributed under the Boost Software License, Version 1.0.
 // (See accompanying file LICENSE_1_0.txt or copy at https://www.boost.org/LICENSE_1_0.txt)
 

include/tao/pq/bind.hpp

@@ -1,4 +1,4 @@
-// Copyright (c) 2021-2024 Daniel Frey and Dr. Colin Hirsch
+// Copyright (c) 2021-2025 Daniel Frey and Dr. Colin Hirsch
 // Distributed under the Boost Software License, Version 1.0.
 // (See accompanying file LICENSE_1_0.txt or copy at https://www.boost.org/LICENSE_1_0.txt)
 

include/tao/pq/connection.hpp

@@ -1,4 +1,4 @@
-// Copyright (c) 2016-2024 Daniel Frey and Dr. Colin Hirsch
+// Copyright (c) 2016-2025 Daniel Frey and Dr. Colin Hirsch
 // Distributed under the Boost Software License, Version 1.0.
 // (See accompanying file LICENSE_1_0.txt or copy at https://www.boost.org/LICENSE_1_0.txt)
 
@@ -23,6 +23,7 @@
 #include <tao/pq/internal/poll.hpp>
 #include <tao/pq/internal/zsv.hpp>
 #include <tao/pq/isolation_level.hpp>
+#include <tao/pq/log.hpp>
 #include <tao/pq/notification.hpp>
 #include <tao/pq/parameter.hpp>
 #include <tao/pq/pipeline_status.hpp>
@@ -53,6 +54,7 @@ namespace tao::pq
       friend class connection_pool;
       friend class table_reader;
       friend class table_writer;
+      friend class transaction;
       friend class transaction_base;
 
       friend class internal::top_level_transaction;
@@ -66,6 +68,7 @@ namespace tao::pq
       std::function< poll::callback > m_poll;
       std::function< void( const notification& ) > m_notification_handler;
       std::map< std::string, std::function< void( const char* ) >, std::less<> > m_notification_handlers;
+      std::shared_ptr< log > m_log;
 
       [[nodiscard]] auto escape_identifier( const std::string_view identifier ) const -> std::unique_ptr< char, decltype( &PQfreemem ) >;
 
@@ -109,7 +112,7 @@ namespace tao::pq
       };
 
    public:
-      connection( const private_key /*unused*/, const std::string& connection_info, std::function< poll::callback > poll_cb );
+      connection( const private_key /*unused*/, const std::string& connection_info );
 
       connection( const connection& ) = delete;
       connection( connection&& ) = delete;
@@ -118,23 +121,61 @@ namespace tao::pq
 
       ~connection() = default;
 
-      [[nodiscard]] static auto create( const std::string& connection_info, std::function< poll::callback > poll_cb = internal::poll ) -> std::shared_ptr< connection >;
+      [[nodiscard]] static auto create( const std::string& connection_info ) -> std::shared_ptr< connection >;
 
       [[nodiscard]] auto error_message() const -> const char*;
 
-      [[nodiscard]] auto poll_callback() const noexcept -> const std::function< poll::callback >&;
-      void set_poll_callback( std::function< poll::callback > poll_cb ) noexcept;
-      void reset_poll_callback();
+      [[nodiscard]] auto poll_callback() const noexcept -> decltype( auto )
+      {
+         return m_poll;
+      }
+
+      void set_poll_callback( std::function< poll::callback > poll_cb ) noexcept
+      {
+         m_poll = std::move( poll_cb );
+      }
+
+      void reset_poll_callback()
+      {
+         m_poll = internal::poll;
+      }
+
+      [[nodiscard]] auto notification_handler() const noexcept -> decltype( auto )
+      {
+         return m_notification_handler;
+      }
+
+      void set_notification_handler( std::function< void( const notification& ) > handler ) noexcept
+      {
+         m_notification_handler = std::move( handler );
+      }
+
+      void reset_notification_handler() noexcept
+      {
+         m_notification_handler = nullptr;
+      }
 
-      [[nodiscard]] auto notification_handler() const -> std::function< void( const notification& ) >;
       [[nodiscard]] auto notification_handler( const std::string_view channel ) const -> std::function< void( const char* payload ) >;
 
-      void set_notification_handler( const std::function< void( const notification& ) >& handler );
       void set_notification_handler( const std::string_view channel, const std::function< void( const char* payload ) >& handler );
 
-      void reset_notification_handler() noexcept;
       void reset_notification_handler( const std::string_view channel ) noexcept;
 
+      [[nodiscard]] auto log_handler() const noexcept -> decltype( auto )
+      {
+         return m_log;
+      }
+
+      void set_log_handler( const std::shared_ptr< pq::log >& log ) noexcept
+      {
+         m_log = log;
+      }
+
+      void reset_log_handler() noexcept
+      {
+         m_log = nullptr;
+      }
+
       [[nodiscard]] auto status() const noexcept -> connection_status;
       [[nodiscard]] auto transaction_status() const noexcept -> pq::transaction_status;
 
@@ -156,6 +197,10 @@ namespace tao::pq
 
       [[nodiscard]] auto is_busy() const noexcept -> bool;
 
+      [[nodiscard]] auto flush() -> bool;
+
+      void consume_input();
+
       [[nodiscard]] auto direct() -> std::shared_ptr< pq::transaction >;
 
       [[nodiscard]] auto transaction() -> std::shared_ptr< pq::transaction >;
@@ -190,8 +235,15 @@ namespace tao::pq
          return m_timeout;
       }
 
-      void set_timeout( const std::chrono::milliseconds timeout );
-      void reset_timeout() noexcept;
+      void set_timeout( const std::chrono::milliseconds timeout ) noexcept
+      {
+         m_timeout = timeout;
+      }
+
+      void reset_timeout() noexcept
+      {
+         m_timeout = std::nullopt;
+      }
 
       [[nodiscard]] auto password( const internal::zsv passwd, const internal::zsv user, const internal::zsv algorithm = "scram-sha-256" ) -> std::string;