From fd096b1ce6a36a7e6441a7f45a9e8f8a1cf37d6a Mon Sep 17 00:00:00 2001 From: Arne Welzel Date: Tue, 28 Nov 2023 11:39:14 +0100 Subject: [PATCH] logging: delay documentation polishing Based on PR feedback. --- scripts/base/frameworks/logging/main.zeek | 36 +++++++++++-------- src/logging/Manager.cc | 2 +- .../.stderr | 4 +-- .../.stderr | 4 +-- .../.stderr | 4 +-- .../.stderr | 4 +-- 6 files changed, 31 insertions(+), 23 deletions(-) diff --git a/scripts/base/frameworks/logging/main.zeek b/scripts/base/frameworks/logging/main.zeek index 9db95e4e6e..b85a29c3ab 100644 --- a/scripts/base/frameworks/logging/main.zeek +++ b/scripts/base/frameworks/logging/main.zeek @@ -407,12 +407,20 @@ export { ## Maximum delay interval for this stream. ## + ## This value can be increased using :zeek:see:`Log::set_max_delay_interval` + ## after the stream has been created. + ## ## .. :zeek:see:`Log::default_max_delay_interval` + ## .. :zeek:see:`Log::set_max_delay_interval` max_delay_interval: interval &default=default_max_delay_interval; ## Maximum delay queue size of this stream. ## + ## This value can be changed using :zeek:see:`Log::set_max_delay_queue_size` + ## after the stream has been created. + ## ## .. :zeek:see:`Log::default_max_delay_queue_size` + ## .. :zeek:see:`Log::set_max_delay_queue_size` max_delay_queue_size: count &default=default_max_delay_queue_size; }; @@ -626,11 +634,11 @@ export { ## Type of function to invoke when delaying a log write has completed. ## - ## This is similar to a :zeek:see:`Log::StreamPolicyHook`, but a callback - ## of this type is passed to zeek:see:`Log::delay` and executes just before - ## the record is forwarded to the individual log filters. + ## Functions of this type take the same arguments as :zeek:see:`Log::StreamPolicyHook` + ## and act as a callback passed to zeek:see:`Log::delay`. They execute + ## just before the record is forwarded to the individual log filters. ## - ## Returning false from a post delay callback discards the log write. + ## Returning ``F`` from a post delay callback discards the log write. type PostDelayCallback: function(rec: any, id: ID): bool; ## Type of the opaque value returned by :zeek:see:`Log::delay`. These @@ -652,21 +660,21 @@ export { ## Conceptually, the delay is inserted between the execution of the ## zeek:see:`Log::log_stream_policy` hook and the policy hooks of filters. ## - ## Calling this function increases a reference count that can subsequently - ## be released using :zeek:see:`Log::delay_finish`. + ## Calling this function increments a reference count that can subsequently + ## be decremented using :zeek:see:`Log::delay_finish`. ## The delay completes when either the reference count reaches zero, or ## the configured maximum delay interval for the stream expires. The - ## optional *post_delay_callback* is invoked when the delay completed. + ## optional *post_delay_cb* is invoked when the delay completed. ## - ## The *post_delay_callback* function can extend the delay by invoking - ## :zeek:see:`Log::delay`. There's no limit to how often a write can be - ## re-delayed. Further, it can veto the forwarding of the log record - ## to the stream's filters by returning ``F``. If *post_delay_cb* is not - ## provided, it's equivalent to a function solely returning ``T``. + ## The *post_delay_cb* function can extend the delay by invoking + ## :zeek:see:`Log::delay` again. There's no limit to how often a write + ## can be re-delayed. Further, it can discard the log record altogether + ## by returning ``F``. If *post_delay_cb* is not provided, the behavior + ## is equivalent to a no-op callback solely returning ``T``. ## ## id: The ID associated with a logging stream. ## - ## rec: Log record + ## rec: The log record. ## ## post_delay_cb: A callback to invoke when the delay completed. ## @@ -681,7 +689,7 @@ export { ## ## id: The ID associated with a logging stream. ## - ## rec: Log record + ## rec: The log record. ## ## token: The opaque token as returned by :zeek:see:`Log::delay`. ## diff --git a/src/logging/Manager.cc b/src/logging/Manager.cc index 9c450e48d9..15e134889e 100644 --- a/src/logging/Manager.cc +++ b/src/logging/Manager.cc @@ -147,7 +147,7 @@ private: // Has this DelayInfo object been enqueued? bool enqueued = false; - // Iterator pointing this instance in the delay_queue. + // Iterator pointing at this instance in the delay_queue. DelayQueue::const_iterator queue_position; }; diff --git a/testing/btest/Baseline/scripts.base.frameworks.logging.delay.static-errors-2/.stderr b/testing/btest/Baseline/scripts.base.frameworks.logging.delay.static-errors-2/.stderr index 124879e152..e6e75f40cf 100644 --- a/testing/btest/Baseline/scripts.base.frameworks.logging.delay.static-errors-2/.stderr +++ b/testing/btest/Baseline/scripts.base.frameworks.logging.delay.static-errors-2/.stderr @@ -1,4 +1,4 @@ ### BTest baseline data generated by btest-diff. Do not edit. Use "btest -U/-u" to update. Requires BTest >= 0.63. -error in <...>/main.zeek, line 634 and <...>/static-errors.zeek, line 12: type clash (Log::PostDelayCallback and post_delay_cb) -error in <...>/static-errors.zeek, line 12 and <...>/main.zeek, line 634: type mismatch (post_delay_cb and Log::PostDelayCallback) +error in <...>/main.zeek, line 642 and <...>/static-errors.zeek, line 12: type clash (Log::PostDelayCallback and post_delay_cb) +error in <...>/static-errors.zeek, line 12 and <...>/main.zeek, line 642: type mismatch (post_delay_cb and Log::PostDelayCallback) error in <...>/static-errors.zeek, line 12: argument type mismatch in function call (Log::delay(id, to_any_coercerec, post_delay_cb)) diff --git a/testing/btest/Baseline/scripts.base.frameworks.logging.delay.static-errors-3/.stderr b/testing/btest/Baseline/scripts.base.frameworks.logging.delay.static-errors-3/.stderr index d602ff9d4a..b5726af3b5 100644 --- a/testing/btest/Baseline/scripts.base.frameworks.logging.delay.static-errors-3/.stderr +++ b/testing/btest/Baseline/scripts.base.frameworks.logging.delay.static-errors-3/.stderr @@ -1,4 +1,4 @@ ### BTest baseline data generated by btest-diff. Do not edit. Use "btest -U/-u" to update. Requires BTest >= 0.63. -error in <...>/main.zeek, line 639 and <...>/static-errors.zeek, line 8: type clash (Log::DelayToken and 42) -error in <...>/static-errors.zeek, line 8 and <...>/main.zeek, line 639: type mismatch (42 and Log::DelayToken) +error in <...>/main.zeek, line 647 and <...>/static-errors.zeek, line 8: type clash (Log::DelayToken and 42) +error in <...>/static-errors.zeek, line 8 and <...>/main.zeek, line 647: type mismatch (42 and Log::DelayToken) error in <...>/static-errors.zeek, line 8: argument type mismatch in function call (Log::delay_finish(id, to_any_coercerec, 42)) diff --git a/testing/btest/Baseline/scripts.base.frameworks.logging.delay.static-errors-4/.stderr b/testing/btest/Baseline/scripts.base.frameworks.logging.delay.static-errors-4/.stderr index e635f77752..025a9f455d 100644 --- a/testing/btest/Baseline/scripts.base.frameworks.logging.delay.static-errors-4/.stderr +++ b/testing/btest/Baseline/scripts.base.frameworks.logging.delay.static-errors-4/.stderr @@ -1,4 +1,4 @@ ### BTest baseline data generated by btest-diff. Do not edit. Use "btest -U/-u" to update. Requires BTest >= 0.63. -error in <...>/main.zeek, line 639 and <...>/static-errors.zeek, line 8: arithmetic mixed with non-arithmetic (Log::DelayToken and 42) -error in <...>/static-errors.zeek, line 8 and <...>/main.zeek, line 639: type mismatch (42 and Log::DelayToken) +error in <...>/main.zeek, line 647 and <...>/static-errors.zeek, line 8: arithmetic mixed with non-arithmetic (Log::DelayToken and 42) +error in <...>/static-errors.zeek, line 8 and <...>/main.zeek, line 647: type mismatch (42 and Log::DelayToken) error in <...>/static-errors.zeek, line 8: argument type mismatch in function call (Log::delay_finish(id, to_any_coercerec, 42)) diff --git a/testing/btest/Baseline/scripts.base.frameworks.logging.delay.static-errors/.stderr b/testing/btest/Baseline/scripts.base.frameworks.logging.delay.static-errors/.stderr index 8ec6765e9d..292040868f 100644 --- a/testing/btest/Baseline/scripts.base.frameworks.logging.delay.static-errors/.stderr +++ b/testing/btest/Baseline/scripts.base.frameworks.logging.delay.static-errors/.stderr @@ -1,4 +1,4 @@ ### BTest baseline data generated by btest-diff. Do not edit. Use "btest -U/-u" to update. Requires BTest >= 0.63. -error in <...>/main.zeek, line 634 and <...>/static-errors.zeek, line 16: type clash (Log::PostDelayCallback and post_delay_cb) -error in <...>/static-errors.zeek, line 16 and <...>/main.zeek, line 634: type mismatch (post_delay_cb and Log::PostDelayCallback) +error in <...>/main.zeek, line 642 and <...>/static-errors.zeek, line 16: type clash (Log::PostDelayCallback and post_delay_cb) +error in <...>/static-errors.zeek, line 16 and <...>/main.zeek, line 642: type mismatch (post_delay_cb and Log::PostDelayCallback) error in <...>/static-errors.zeek, line 16: argument type mismatch in function call (Log::delay(id, to_any_coercerec, post_delay_cb))