Source Format Enforcement (#1234)

[thirdparty/squid.git] / src / enums.h

diff --git a/src/enums.h b/src/enums.h
index 231ec58819d8af2031d4fb733fb385b087758e16..1b2865413e07d518598c6874202232ebb0bb00fe 100644 (file)
--- a/src/enums.h
+++ b/src/enums.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.
@@ -10,7 +10,7 @@
 #define SQUID_ENUMS_H
 
 enum fd_type {
-    FD_NONE,
+    FD_NONE_TYPE,
     FD_LOG,
     FD_FILE,
     FD_SOCKET,
@@ -31,41 +31,18 @@ typedef enum {
     PEER_MULTICAST
 } peer_t;
 
-typedef enum {
-    CC_PUBLIC = 0,
-    CC_PRIVATE,
-    CC_NO_CACHE,
-    CC_NO_STORE,
-    CC_NO_TRANSFORM,
-    CC_MUST_REVALIDATE,
-    CC_PROXY_REVALIDATE,
-    CC_MAX_AGE,
-    CC_S_MAXAGE,
-    CC_MAX_STALE,
-    CC_MIN_FRESH,
-    CC_ONLY_IF_CACHED,
-    CC_STALE_IF_ERROR,
-    CC_OTHER,
-    CC_ENUM_END /* also used to mean "invalid" */
-} http_hdr_cc_type;
-
-typedef enum {
-    SC_NO_STORE,
-    SC_NO_STORE_REMOTE,
-    SC_MAX_AGE,
-    SC_CONTENT,
-    SC_OTHER,
-    SC_ENUM_END /* also used to mean "invalid" */
-} http_hdr_sc_type;
-
 typedef enum _mem_status_t {
     NOT_IN_MEMORY,
     IN_MEMORY
 } mem_status_t;
 
 typedef enum {
+    /// Has not considered whether to send ICP queries to peers yet.
     PING_NONE,
+    /// Sent ICP queries to peers and still awaiting responses.
     PING_WAITING,
+    /// Not waiting for ICP responses now and will not send ICP queries later.
+    /// The ICP queries may (or may not) have been sent earlier.
     PING_DONE
 } ping_status_t;
 
@@ -74,10 +51,21 @@ typedef enum {
     STORE_PENDING
 } store_status_t;
 
+/// StoreEntry relationship with a disk cache
 typedef enum {
+    /// StoreEntry is currently not associated with any disk store entry.
+    /// Does not guarantee (or preclude!) a matching disk store entry existence.
     SWAPOUT_NONE,
+    /// StoreEntry is being swapped out to the associated disk store entry.
+    /// Guarantees the disk store entry existence.
     SWAPOUT_WRITING,
-    SWAPOUT_DONE
+    /// StoreEntry is associated with a complete (i.e., fully swapped out) disk store entry.
+    /// Guarantees the disk store entry existence.
+    SWAPOUT_DONE,
+    /// StoreEntry is associated with an unusable disk store entry.
+    /// Swapout attempt has failed. The entry should be marked for eventual deletion.
+    /// Guarantees the disk store entry existence.
+    SWAPOUT_FAILED
 } swap_status_t;
 
 typedef enum {
@@ -94,18 +82,40 @@ typedef enum {
  */
 enum {
     ENTRY_SPECIAL,
-    ENTRY_REVALIDATE,
+    ENTRY_REVALIDATE_ALWAYS,
+
+    /// Tiny Store writes are likely. The writes should be aggregated together
+    /// before Squid announces the new content availability to the store
+    /// clients. For example, forming a cached HTTP response header may result
+    /// in dozens of StoreEntry::write() calls, many of which adding as little
+    /// as two bytes. Sharing those small writes with the store clients
+    /// increases overhead, especially because the client code can do nothing
+    /// useful with the written content until the whole response header is
+    /// stored. Might be combined with ENTRY_FWD_HDR_WAIT. TODO: Rename to
+    /// ENTRY_DELAY_WHILE_COALESCING to emphasize the difference from and
+    /// similarity with ENTRY_FWD_HDR_WAIT.
     DELAY_SENDING,
-    RELEASE_REQUEST,
+    RELEASE_REQUEST, ///< prohibits making the key public
     REFRESH_REQUEST,
-    ENTRY_CACHABLE_RESERVED_FOR_FUTURE_USE,
+    ENTRY_REVALIDATE_STALE,
     ENTRY_DISPATCHED,
     KEY_PRIVATE,
+
+    /// The current entry response may change. The contents of an entry in this
+    /// state must not be shared with its store clients. For example, Squid
+    /// receives (and buffers) an HTTP/504 response but may decide to retry that
+    /// transaction to receive a successful response from another server
+    /// instead. Might be combined with DELAY_SENDING. TODO: Rename to
+    /// ENTRY_DELAY_WHILE_WOBBLING to emphasize the difference from and
+    /// similarity with DELAY_SENDING.
     ENTRY_FWD_HDR_WAIT,
     ENTRY_NEGCACHED,
     ENTRY_VALIDATED,
     ENTRY_BAD_LENGTH,
-    ENTRY_ABORTED
+    ENTRY_ABORTED,
+    /// Whether the entry serves collapsed hits now.
+    /// Meaningful only for public entries.
+    ENTRY_REQUIRES_COLLAPSING
 };
 
 /*
@@ -115,12 +125,12 @@ enum {
 typedef enum {
     STREAM_NONE,        /* No particular status */
     STREAM_COMPLETE,        /* All data has been flushed, no more reads allowed */
-    /* an unpredicted end has occured, no more
-     * reads occured, but no need to tell
-     * downstream that an error occured
+    /* an unpredicted end has occurred, no more
+     * reads occurred, but no need to tell
+     * downstream that an error occurred
      */
     STREAM_UNPLANNED_COMPLETE,
-    /* An error has occured in this node or an above one,
+    /* An error has occurred in this node or an above one,
      * and the node is not generating an error body / it's
      * midstream
      */
@@ -150,14 +160,6 @@ enum {
     STORE_LOG_SWAPOUTFAIL
 };
 
-/* parse state of HttpReply or HttpRequest */
-typedef enum {
-    psReadyToParseStartLine = 0,
-    psReadyToParseHeaders,
-    psParsed,
-    psError
-} HttpMsgParseState;
-
 enum {
     PCTILE_HTTP,
     PCTILE_ICP_QUERY,
@@ -206,12 +208,6 @@ typedef enum {
     DIGEST_READ_DONE
 } digest_read_state_t;
 
-/* Distinguish between Request and Reply (for header mangling) */
-enum {
-    ROR_REQUEST,
-    ROR_REPLY
-};
-
 /* CygWin & Windows NT Port */
 #if _SQUID_WINDOWS_
 /*