Source Format Enforcement (#1234)

[thirdparty/squid.git] / src / base / Packable.h

diff --git a/src/base/Packable.h b/src/base/Packable.h
index fd1dc01ad08a8d4a26f75a6da5a694a8d7f4bb54..046c118558e93ec2f89a0cbf1e80ff2682df73a6 100644 (file)
--- a/src/base/Packable.h
+++ b/src/base/Packable.h
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 1996-2015 The Squid Software Foundation and contributors
+ * Copyright (C) 1996-2023 The Squid Software Foundation and contributors
  *
  * Squid software is distributed under GPLv2+ license and includes
  * contributions from numerous individuals and organizations.
@@ -42,13 +42,18 @@
  * storeAppend. Packable buffer objects retain the data such that it can be
  * flushed later to Comm::Write.
  *
- * Thus, one can write just one function that will take a Packer* pointer
+ * Thus, one can write just one function that will take a Packable object
  * and either "pack" things for Comm::Write or "append" things to Store,
  * depending on actual Packable object supplied.
+ *
+ * XXX: Misnamed. This is a Packer or Packager API (i.e., "something that packs
+ * or packages others"); this is not a "something that can be packed" API.
  */
 class Packable
 {
 public:
+    virtual ~Packable() {}
+
     /// Appends a c-string to existing packed data.
     virtual void append(const char *buf, int size) = 0;
 
@@ -60,26 +65,34 @@ public:
         vappendf(fmt, args);
         va_end(args);
     }
-#if 0
-    /*
-     * \note  we use Printf instead of printf so the compiler won't
-     *        think we're calling the libc printf()
-     */
-    void Printf(const char *fmt,...) PRINTF_FORMAT_ARG2
-    {
-        va_list args;
-        va_start(args, fmt);
-        vappendf(fmt, args);
-        va_end(args);
-    }
-#endif
 
     /** Append operation, with vsprintf(3)-style arguments.
      *
      * \note arguments may be evaluated more than once, be careful
      *       of side-effects
+     *
+     * XXX: This method either should not exist or should not be virtual.
+     * Kids should not be forced to re-implement vappendf() logic.
+     * That logic should be implemented once, using other [Packable] APIs.
+     * Packable is not about providing a printf(3) service. Packable
+     * is about writing opaque data to various custom destinations.
      */
     virtual void vappendf(const char *fmt, va_list ap) = 0;
+
+    /** start buffering appends (if relevant)
+     *
+     * Indicates that a number of small appends are about to
+     * follow so would be detrimental to trigger expensive
+     * activity on each.
+     */
+    virtual void buffer() {}
+
+    /** perform a buffer flush (if relevant)
+     *
+     * Used by code such as PackableStream, that assumes the
+     * Packable leads to some form of output buffer.
+     */
+    virtual void flush() {}
 };
 
 #endif /* SQUID_SRC_BASE_PACKABLE_H */