+++ /dev/null
-/*
- * Copyright (c) 2016 Cisco and/or its affiliates.
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at:
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
-*/
-
-#error do not #include this file!
-
-/** \file
-
- Cooperative multi-tasking thread support.
-
- Vlib provides a lightweight cooperative multi-tasking thread
- model. Context switching costs a setjmp/longjump pair. It's not
- unreasonable to put vlib threads to sleep for 10us.
-
- The graph node scheduler invokes these processes in much the same
- way as traditional vector-processing run-to-completion graph
- nodes; plus-or-minus a setjmp/longjmp pair required to switch
- stacks. Simply set the vlib_node_registration_t type field to
- VLIB_NODE_TYPE_PROCESS. Process is a misnomer; these are threads.
-
- As of this writing, the default stack size is 2<<15;
- 32kb. Initialize the node registration's
- process_log2_n_stack_bytes member as needed. The graph node
- dispatcher makes some effort to detect stack overrun. We map a
- no-access page below each thread stack.
-
- Process node dispatch functions are expected to be while(1) { }
- loops which suspend when not otherwise occupied, and which must
- not run for unreasonably long periods of time. Unreasonably long
- is an application-dependent concept. Over the years, we have
- constructed frame-size sensitive control-plane nodes which will
- use a much higher fraction of the available CPU bandwidth when the
- frame size is low. Classic example: modifying forwarding
- tables. So long as the table-builder leaves the forwarding tables
- in a valid state, one can suspend the table builder to avoid
- dropping packets as a result of control-plane activity.
-
- Process nodes can suspend for fixed amounts of time, or until another
- entity signals an event, or both. See the example below.
-
- When running in VLIB process context, one must pay strict attention to
- loop invariant issues. If one walks a data structure and calls a
- function which may suspend, one had best know by construction that it
- cannot change. Often, it s best to simply make a snapshot copy of a
- data structure, walk the copy at leisure, then free the copy.
-
- Here's an example:
-
- <code><pre>
- \#define EXAMPLE_POLL_PERIOD 10.0
-
- static uword
- example_process (vlib_main_t * vm, vlib_node_runtime_t * rt,
- vlib_frame_t * f)
- {
- f64 poll_time_remaining;
- uword event_type, *event_data = 0;
-
- poll_time_remaining = EXAMPLE_POLL_PERIOD;
- while (1)
- {
- int i;
-
- // Sleep until next periodic call due,
- // or until we receive event(s)
- //
- poll_time_remaining =
- vlib_process_wait_for_event_or_clock (vm, poll_time_remaining);
-
- event_type = vlib_process_get_events (vm, &event_data);
- switch (event_type)
- {
- case ~0: // no events => timeout
- break;
-
- case EVENT1:
- for (i = 0; i < vec_len (event_data); i++)
- handle_event1 (mm, event_data[i]);
- break;
-
- case EVENT2:
- for (i = 0; i < vec_len (event_data); i++)
- handle_event2 (vm, event_data[i]);
- break;
-
- // ... and so forth for each event type
-
- default:
- // This should never happen...
- clib_warning ("BUG: unhandled event type %d",
- event_type);
- break;
- }
- vec_reset_length (event_data);
-
- // Timer expired, call periodic function
- if (vlib_process_suspend_time_is_zero (poll_time_remaining))
- {
- example_periodic (vm);
- poll_time_remaining = EXAMPLE_POLL_PERIOD;
- }
- }
- // NOTREACHED
- return 0;
- }
-
- static VLIB_REGISTER_NODE (example_node) = {
- .function = example_process,
- .type = VLIB_NODE_TYPE_PROCESS,
- .name = "example-process",
- };
- </pre></code>
-
- In this example, the VLIB process node waits for an event to
- occur, or for 10 seconds to elapse. The code demuxes on the event
- type, calling the appropriate handler function.
-
- Each call to vlib_process_get_events returns a vector of
- per-event-type data passed to successive vlib_process_signal_event
- calls; vec_len (event_data) >= 1. It is an error to process only
- event_data[0].
-
- Resetting the event_data vector-length to 0 by calling
- vec_reset_length (event_data) - instead of calling vec_free (...)
- - means that the event scheme doesn t burn cycles continuously
- allocating and freeing the event data vector. This is a common
- coding pattern, well worth using when appropriate.
-*/
-
-/*
- * fd.io coding-style-patch-verification: ON
- *
- * Local Variables:
- * eval: (c-set-style "gnu")
- * End:
- */
Code Review / vpp.git / blobdiff