Merge branch 'main' into feature/serialize-buffer-refactor

docs/fpp-spec.html

@@ -12037,7 +12037,7 @@ equivalent.</p>
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2025-11-04 08:21:20 -0800
+Last updated 2025-11-06 15:59:49 -0800
 </div>
 </div>
 <script src="code-prettify/run_prettify.js"></script>

docs/fpp-users-guide.html

@@ -7817,7 +7817,9 @@ or a few warnings.</p>
 <div class="paragraph">
 <p>To achieve this behavior, you can write the keyword <code>throttle</code> and a
 numeric expression after the format string.
-The expression must evaluate to a constant value <em>n</em>.
+The expression must evaluate to a constant value <em>n</em>, where <em>n</em> is a number
+greater than zero.
+<em>n</em> is called the <strong>maximum throttle count</strong>.
 After an instance of the component has emitted the event <em>n</em> times, it will
 stop emitting the event.
 Here is an example:</p>
@@ -7853,16 +7855,101 @@ passive component EventThrottling {
 </div>
 </div>
 <div class="paragraph">
-<p>In this example, event <code>E</code> will be throttled after the component
+<p>In this example, event <code>Event1</code> will be throttled after the component
 instance has emitted it ten times.</p>
 </div>
 <div class="paragraph">
-<p>Once an event is throttled, the component instance will no longer
+<p>Once an event is throttled, the component
-emit the event until the throttling is canceled.
+instance will no longer emit the event until the throttling is reset.
-Typically, the canceling happens via a FSW command.
+There are two ways to reset the throttling of an event: manually and
+automatically.</p>
+</div>
+<div class="paragraph">
+<p><strong>Manual reset:</strong>
+To manually reset throttling for events,
+you can use a <a href="#Defining-Components_Commands">command</a>.
+For example, you can define a command <code>CLEAR_EVENT_THROTTLE</code>
+that resets throttling for all throttled events.
+You can implement this command by calling functions
+that reset the throttle counts to zero.
+The auto-generated C&#43;&#43; code provides one such function for
+each event with throttling.
 For details, see the
 <a href="https://fprime.jpl.nasa.gov/devel/docs/user-manual/">F Prime User Manual</a>.</p>
 </div>
+<div class="paragraph">
+<p><strong>Automatic reset:</strong>
+You can also specify in FPP that the throttling for an event should be reset
+automatically after a specified amount of time.
+To do this, you write <code>every</code> and a time interval after the maximum throttle
+count.
+The time interval is a <a href="#Defining-Constants_Expressions_Struct-Values">struct
+value expression</a> with two members: <code>seconds</code> and <code>useconds</code>.
+<code>useconds</code> is short for &#8220;microseconds.&#8221;
+Each member must evaluate to an integer value.
+Either or both of the members can be omitted; an omitted member evaluates to
+zero.</p>
+</div>
+<div class="paragraph">
+<p>Here is an example:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="prettyprint highlight"><code data-lang="fpp">@ Component for illustrating event throttling with timeouts
+passive component EventThrottlingWithTimeout {
+
+  # ----------------------------------------------------------------------
+  # Ports
+  # ----------------------------------------------------------------------
+
+  @ Event port
+  event port eventOut
+
+  @ Text event port
+  text event port textEventOut
+
+  @ Time get port
+  time get port timeGetOut
+
+  # ----------------------------------------------------------------------
+  # Events
+  # ----------------------------------------------------------------------
+
+  @ Event 1
+  event Event1 severity warning high \
+    format "Event 1 occurred" \
+    throttle 10 every { seconds = 2 }
+
+  @ Event 2
+  event Event2 severity warning high \
+    format "Event 2 occurred" \
+    throttle 10 every { seconds = 2, useconds = 500000 }
+
+  @ Event 3
+  event Event3 severity warning high \
+    format "Event 3 occurred" \
+    throttle 10 every { useconds = 500000 }
+
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>In this example, an instance of <code>EventThrottlingWithTimeout</code> will emit events
+at the following rates:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><code>Event1</code>: Up to 10 events every 2 seconds.</p>
+</li>
+<li>
+<p><code>Event2</code>: Up to 10 events every 2.5 seconds.</p>
+</li>
+<li>
+<p><code>Event3</code>: Up to 10 events every 0.5 seconds.</p>
+</li>
+</ul>
+</div>
 </div>
 </div>
 <div class="sect2">
@@ -16133,7 +16220,7 @@ serialized according to its
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2025-11-04 08:22:00 -0800
+Last updated 2025-11-06 16:00:29 -0800
 </div>
 </div>
 <script src="code-prettify/run_prettify.js"></script>

docs/index.html

@@ -4,7 +4,7 @@
 <meta charset="UTF-8">
 <meta http-equiv="X-UA-Compatible" content="IE=edge">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
-<meta name="generator" content="Asciidoctor 2.0.23">
+<meta name="generator" content="Asciidoctor 2.0.20">
 <title>F Prime Prime (FPP)</title>
 <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700">
 <style>
@@ -140,7 +140,7 @@ p a>code:hover{color:rgba(0,0,0,.9)}
 #content::before{content:none}
 #header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0}
 #header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf}
-#header>h1:only-child{border-bottom:1px solid #dddddf;padding-bottom:8px}
+#header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px}
 #header .details{border-bottom:1px solid #dddddf;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:flex;flex-flow:row wrap}
 #header .details span:first-child{margin-left:-.125em}
 #header .details span.email a{color:rgba(0,0,0,.85)}
@@ -162,7 +162,6 @@ p a>code:hover{color:rgba(0,0,0,.9)}
 #toctitle{color:#7a2518;font-size:1.2em}
 @media screen and (min-width:768px){#toctitle{font-size:1.375em}
 body.toc2{padding-left:15em;padding-right:0}
-body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px}
 #toc.toc2{margin-top:0!important;background:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #e7e7e9;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto}
 #toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em}
 #toc.toc2>ul{font-size:.9em;margin-bottom:0}
@@ -328,7 +327,7 @@ a.image{text-decoration:none;display:inline-block}
 a.image object{pointer-events:none}
 sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super}
 sup.footnote a,sup.footnoteref a{text-decoration:none}
-sup.footnote a:active,sup.footnoteref a:active,#footnotes .footnote a:first-of-type:active{text-decoration:underline}
+sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline}
 #footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em}
 #footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0}
 #footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em}
@@ -464,7 +463,7 @@ generated code.</p>
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2025-11-04 08:20:56 -0800
+Last updated 2025-02-18 09:43:03 -0800
 </div>
 </div>
 </body>

docs/users-guide/Defining-Components.adoc

@@ -1507,7 +1507,9 @@ or a few warnings.
 
 To achieve this behavior, you can write the keyword `throttle` and a
 numeric expression after the format string.
-The expression must evaluate to a constant value _n_.
+The expression must evaluate to a constant value _n_, where _n_ is a number
+greater than zero.
+_n_ is called the *maximum throttle count*.
 After an instance of the component has emitted the event _n_ times, it will
 stop emitting the event.
 Here is an example:
@@ -1542,15 +1544,89 @@ passive component EventThrottling {
 }
 ----
 
-In this example, event `E` will be throttled after the component
+In this example, event `Event1` will be throttled after the component
 instance has emitted it ten times.
 
-Once an event is throttled, the component instance will no longer
+Once an event is throttled, the component
-emit the event until the throttling is canceled.
+instance will no longer emit the event until the throttling is reset.
-Typically, the canceling happens via a FSW command.
+There are two ways to reset the throttling of an event: manually and 
+automatically.
+
+*Manual reset:*
+To manually reset throttling for events,
+you can use a <<Defining-Components_Commands,command>>.
+For example, you can define a command `CLEAR_EVENT_THROTTLE`
+that resets throttling for all throttled events.
+You can implement this command by calling functions
+that reset the throttle counts to zero.
+The auto-generated {cpp} code provides one such function for
+each event with throttling.
 For details, see the
 https://fprime.jpl.nasa.gov/devel/docs/user-manual/[F Prime User Manual].
 
+*Automatic reset:*
+You can also specify in FPP that the throttling for an event should be reset
+automatically after a specified amount of time.
+To do this, you write `every` and a time interval after the maximum throttle 
+count.
+The time interval is a <<Defining-Constants_Expressions_Struct-Values,struct 
+value expression>> with two members: `seconds` and `useconds`.
+`useconds` is short for "`microseconds.`"
+Each member must evaluate to an integer value.
+Either or both of the members can be omitted; an omitted member evaluates to 
+zero.
+
+Here is an example:
+
+[source,fpp]
+----
+@ Component for illustrating event throttling with timeouts
+passive component EventThrottlingWithTimeout {
+
+  # ----------------------------------------------------------------------
+  # Ports
+  # ----------------------------------------------------------------------
+
+  @ Event port
+  event port eventOut
+
+  @ Text event port
+  text event port textEventOut
+
+  @ Time get port
+  time get port timeGetOut
+
+  # ----------------------------------------------------------------------
+  # Events
+  # ----------------------------------------------------------------------
+
+  @ Event 1
+  event Event1 severity warning high \
+    format "Event 1 occurred" \
+    throttle 10 every { seconds = 2 }
+
+  @ Event 2
+  event Event2 severity warning high \
+    format "Event 2 occurred" \
+    throttle 10 every { seconds = 2, useconds = 500000 }
+
+  @ Event 3
+  event Event3 severity warning high \
+    format "Event 3 occurred" \
+    throttle 10 every { useconds = 500000 }
+
+}
+----
+
+In this example, an instance of `EventThrottlingWithTimeout` will emit events
+at the following rates:
+
+* `Event1`: Up to 10 events every 2 seconds.
+
+* `Event2`: Up to 10 events every 2.5 seconds.
+
+* `Event3`: Up to 10 events every 0.5 seconds.
+
 === Telemetry
 
 When defining an F Prime component, you may specify one or more