diff options
author | Damjan Marion <damarion@cisco.com> | 2016-12-19 23:05:39 +0100 |
---|---|---|
committer | Damjan Marion <damarion@cisco.com> | 2016-12-28 12:25:14 +0100 |
commit | 7cd468a3d7dee7d6c92f69a0bb7061ae208ec727 (patch) | |
tree | 5de62f8dbd3a752f5a676ca600e43d2652d1ff1a /vlib/vlib/vlib_process_doc.h | |
parent | 696f1adec0df3b8f161862566dd9c86174302658 (diff) |
Reorganize source tree to use single autotools instance
Change-Id: I7b51f88292e057c6443b12224486f2d0c9f8ae23
Signed-off-by: Damjan Marion <damarion@cisco.com>
Diffstat (limited to 'vlib/vlib/vlib_process_doc.h')
-rw-r--r-- | vlib/vlib/vlib_process_doc.h | 147 |
1 files changed, 0 insertions, 147 deletions
diff --git a/vlib/vlib/vlib_process_doc.h b/vlib/vlib/vlib_process_doc.h deleted file mode 100644 index a47c5e4bbe4..00000000000 --- a/vlib/vlib/vlib_process_doc.h +++ /dev/null @@ -1,147 +0,0 @@ -/* - * 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: - */ |