]>
git.ipfire.org Git - thirdparty/squid.git/blob - src/base/Packable.h
2 * Copyright (C) 1996-2023 The Squid Software Foundation and contributors
4 * Squid software is distributed under GPLv2+ license and includes
5 * contributions from numerous individuals and organizations.
6 * Please see the COPYING and CONTRIBUTORS files for details.
9 #ifndef SQUID_SRC_BASE_PACKABLE_H
10 #define SQUID_SRC_BASE_PACKABLE_H
13 * A uniform interface to store-like modules
18 * We have two major interfaces Comm and Store, which take a variety of
19 * different data buffering objects and have different output actions
20 * to be performed on data.
22 * Store has a nice storeAppend[Printf] capability which makes "storing"
23 * things easy and painless.
25 * Comm lacks commAppend[Printf] because Comm does not handle its own
26 * buffers (no mem_obj equivalent for Comm).
28 * Thus, if one wants to be able to Store _and_ Comm::Write an object, 'e
29 * has to implement almost identical functions for using all the data
30 * storage objects and their associated actions. Doing this for all the
31 * available data storage types is a tedious nightmare of almost-duplicated
37 * Objects inheriting from Packable provide a uniform interface for code to
38 * assemble data before passing to Store and Comm modules.
40 * Packable objects have their own append and printf routines that "know"
41 * where to send incoming data. In case of Store interface, sending data to
42 * storeAppend. Packable buffer objects retain the data such that it can be
43 * flushed later to Comm::Write.
45 * Thus, one can write just one function that will take a Packable object
46 * and either "pack" things for Comm::Write or "append" things to Store,
47 * depending on actual Packable object supplied.
49 * XXX: Misnamed. This is a Packer or Packager API (i.e., "something that packs
50 * or packages others"); this is not a "something that can be packed" API.
55 virtual ~Packable() {}
57 /// Appends a c-string to existing packed data.
58 virtual void append(const char *buf
, int size
) = 0;
60 /// Append operation with printf-style arguments.
61 void appendf(const char *fmt
,...) PRINTF_FORMAT_ARG2
69 /** Append operation, with vsprintf(3)-style arguments.
71 * \note arguments may be evaluated more than once, be careful
74 * XXX: This method either should not exist or should not be virtual.
75 * Kids should not be forced to re-implement vappendf() logic.
76 * That logic should be implemented once, using other [Packable] APIs.
77 * Packable is not about providing a printf(3) service. Packable
78 * is about writing opaque data to various custom destinations.
80 virtual void vappendf(const char *fmt
, va_list ap
) = 0;
82 /** start buffering appends (if relevant)
84 * Indicates that a number of small appends are about to
85 * follow so would be detrimental to trigger expensive
88 virtual void buffer() {}
90 /** perform a buffer flush (if relevant)
92 * Used by code such as PackableStream, that assumes the
93 * Packable leads to some form of output buffer.
95 virtual void flush() {}
98 #endif /* SQUID_SRC_BASE_PACKABLE_H */