http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/f245f6aa/develop/os/core_os/event_queue/event_queue/index.html ---------------------------------------------------------------------- diff --git a/develop/os/core_os/event_queue/event_queue/index.html b/develop/os/core_os/event_queue/event_queue/index.html index 8d45ba9..2b7f7ab 100644 --- a/develop/os/core_os/event_queue/event_queue/index.html +++ b/develop/os/core_os/event_queue/event_queue/index.html @@ -700,23 +700,20 @@ </div> <h1 id="event-queues">Event Queues</h1> -<p>Event queue is a way for a task to serialize events sent to it. This makes it easy to process events required to happen inside the task's context. Events may arrive either from an interrupt handler, or from another task.</p> +<p>An event queue allows a task to serialize incoming events and simplify event processing. Events are stored in a queue and a task removes and processes an event from the queue. An event is processed in the context of this task. Events may be generated by <a href="../../callout/callout/">OS callouts</a>, interrupt handlers, and other tasks. </p> <h3 id="description">Description</h3> -<p>Events arrive in form the of a data structure <code>struct os_event</code> and -they are queued to another data structure <code>struct os_eventq</code>.</p> -<p>The Event Queue must be initialized before trying to add events to -it. This is done using <code>os_eventq_init()</code>.</p> -<p>A common way of using event queues is to have a task loop while calling <code>os_eventq_get()</code>, -waiting for work to do. Other tasks (or interrupts) then call <code>os_eventq_put()</code> -to wake it up. Once an event has been queued, the task waiting on that queue is woken up. The event dispatching logic is built into each event via a callback function pointer. The task handler can simply pull events -off the queue and call its callback handler. The processing task would then act according to the event type. </p> -<p>When <code>os_event</code> is queued, it should not be freed until processing task is done with it.</p> -<p>It is assumed that there is only one task consuming events from an event queue. Only one task should be sleeping on a particular <code>os_eventq</code> at a time.</p> -<p>Note that <a href="../../callout/callout/">os_callout</a> subsystem assumes that event queue is used as the wakeup mechanism.</p> +<p>Mynewt's event queue model uses callback functions to process events. Each event is associated with a callback function that is called to process the event. This model enables a library package, that uses events in its implementation but does not have real-time timing requirements, to use an application event queue instead of creating a dedicated event queue and task to process its events. The callback function executes in the context of the task that the application creates to manage the event queue. This model reduces an application's memory requirement because memory must be allocated for the task's stack when a task is created. A package that has real-time timing requirements and must run at a specific task priority should create a dedicated event queue and task to process its events.</p> +<p>In the Mynewt model, a package defines its events and implements the callback functions for the events. A package that does not have real-time timing requirements should use Mynewt's default event queue for its events. The callback function for an event from the Mynewt default event queue is executed in the context of the application main task. A package can, optionally, export a function that allows an application to specify the event queue for the package to use. (See the example in the <code>os_eventq_designate()</code> function description on how to write such a function.) The application task handler that manages the event queue simply pulls events from the event queue and executes the event's callback function in its context. </p> +<p>A common way that Mynewt applications or packages process events from an event queue is to have a task that executes in an infinite loop and calls the <code>os_eventq_get()</code> function to dequeue and return the event from the head of the event queue. The task then calls the event callback function to process the event. The <code>os_eventq_get()</code> function puts the task in to the <code>sleeping</code> state when there are no events on the queue. (See <a href="../../context_switch/context_switch/">Scheduler</a> for more information on task execution states.) Other tasks (or interrupts) call the <code>os_eventq_put()</code> function to add an event to the queue. The <code>os_eventq_put()</code> function determines whether a task is blocked waiting for an event on the queue and puts the task into the <code>ready-to-run</code> state. </p> +<p>A task can use the <code>os_eventq_run()</code> wrapper function that calls the <code>os_eventq_get()</code> function to dequeue an event from the queue and then calls the event callback function to process the event.</p> +<p>Note:</p> +<ul> +<li>Only one task should consume or block waiting for events from an event queue.</li> +<li>The <a href="../../callout/callout/">os_callout</a> subsystem uses events for timer expiration notification.</li> +</ul> <h3 id="data-structures">Data structures</h3> -<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">typedef</span> <span style="color: #A90D91">void</span> <span style="color: #000000">os_event_fn</span>(<span style="color: #A90D91">struct</span> <span style="color: #000000">os_event</span> <span style="color: #000000">*ev</span>); - -<span style="color: #A90D91">struct</span> <span style="color: #000000">os_event</span> { +<p>The <code>os_event</code> structure defines an event and has the following fields:</p> +<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">struct</span> <span style="color: #000000">os_event</span> { <span style="color: #A90D91">uint8_t</span> <span style="color: #000000">ev_queued</span>; <span style="color: #000000">os_event_fn</span> <span style="color: #000000">*ev_cb</span>; <span style="color: #A90D91">void</span> <span style="color: #000000">*ev_arg</span>; @@ -735,15 +732,15 @@ off the queue and call its callback handler. The processing task would then act <tbody> <tr> <td><code>ev_queued</code></td> -<td>Internal field, which tells whether event is linked into an <em>os_eventq</em> already</td> +<td>Internal field that indicates whether this event is currently linked to an event queue</td> </tr> <tr> <td><code>ev_cb</code></td> -<td>A callback function pointer that is called when a new event arrives on the queue</td> +<td>Pointer to the callback function to call to process this event</td> </tr> <tr> <td><code>ev_arg</code></td> -<td>Can be used further as input to task processing this event</td> +<td>Pointer to an optional opaque data that the callback function uses to process this event</td> </tr> <tr> <td><code>ev_next</code></td> @@ -751,39 +748,29 @@ off the queue and call its callback handler. The processing task would then act </tr> </tbody> </table> -<p>With the callback function pointer, the dispatch logic gets built into each event. The task handler simply pulls an event off its queue and blindly calls its callback function. A helper function was added to do just this: -<code>os_eventq_run()</code>. As an example, the task handler for the bleprph application is below:</p> -<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">static</span> <span style="color: #A90D91">void</span> -<span style="color: #000000">bleprph_task_handler</span>(<span style="color: #A90D91">void</span> <span style="color: #000000">*unused</span>) -{ - <span style="color: #A90D91">while</span> (<span style="color: #1C01CE">1</span>) { - <span style="color: #000000">os_eventq_run</span>(<span style="color: #000000">&bleprph_evq</span>); - } -} +<p>An event callback function has the following function prototype:</p> +<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">typedef</span> <span style="color: #A90D91">void</span> <span style="color: #000000">os_event_fn</span>(<span style="color: #A90D91">struct</span> <span style="color: #000000">os_event</span> <span style="color: #000000">*ev</span>); </pre></div> -<p>The callback associated with an event is specified when the event gets -initialized. For example, here are some statically-initialized events -in the NimBLE host:</p> +<p>A pointer to the <code>os_event</code> structure for the event is passed as an argument to the callback function. </p> +<p>Notes: If the memory for the <code>os_event</code> structure is dynamically allocated: </p> +<ul> +<li>You must not free the memory for an event that is currently on an event queue.</li> +<li>You must free the memory in the callback function after it completes processing the event.</li> +</ul> +<p>You must set the callback function for an event when you initialize the event. For example, here is an example of a statically-initialized event in the NimBLE host:</p> <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">static</span> <span style="color: #A90D91">void</span> <span style="color: #000000">ble_hs_event_tx_notify</span>(<span style="color: #A90D91">struct</span> <span style="color: #000000">os_event</span> <span style="color: #000000">*ev</span>); -<span style="color: #A90D91">static</span> <span style="color: #A90D91">void</span> <span style="color: #000000">ble_hs_event_reset</span>(<span style="color: #A90D91">struct</span> <span style="color: #000000">os_event</span> <span style="color: #000000">*ev</span>); <span style="color: #177500">/** OS event - triggers tx of pending notifications and indications. */</span> <span style="color: #A90D91">static</span> <span style="color: #A90D91">struct</span> <span style="color: #000000">os_event</span> <span style="color: #000000">ble_hs_ev_tx_notifications</span> <span style="color: #000000">=</span> { .<span style="color: #000000">ev_cb</span> <span style="color: #000000">=</span> <span style="color: #000000">ble_hs_event_tx_notify</span>, }; - -<span style="color: #177500">/** OS event - triggers a full reset. */</span> -<span style="color: #A90D91">static</span> <span style="color: #A90D91">struct</span> <span style="color: #000000">os_event</span> <span style="color: #000000">ble_hs_ev_reset</span> <span style="color: #000000">=</span> { - .<span style="color: #000000">ev_cb</span> <span style="color: #000000">=</span> <span style="color: #000000">ble_hs_event_reset</span>, -}; </pre></div> -<p>The callback function receives a single parameter: a -pointer to the event being processed. If the event is allocated -dynamically, the callback function should free the event. </p> +<p><br> <br /> +The <code>os_eventq</code> structure defines an event queue and has the following fields: </p> <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">struct</span> <span style="color: #000000">os_eventq</span> { <span style="color: #A90D91">struct</span> <span style="color: #000000">os_task</span> <span style="color: #000000">*evq_task</span>; <span style="color: #000000">STAILQ_HEAD</span>(, <span style="color: #000000">os_event</span>) <span style="color: #000000">evq_list</span>; @@ -801,16 +788,17 @@ dynamically, the callback function should free the event. </p> <tbody> <tr> <td><code>evq_task</code></td> -<td>Pointer to task if there is task sleeping on <em>os_eventq_get()</em></td> +<td>Pointer to the task, if any, that is waiting (in the <code>sleeping</code> state) for the <code>os_eventq_get()</code> function to return an event</td> </tr> <tr> <td><code>evq_list</code></td> -<td>Queue head for list of events in this queue</td> +<td>Head of the list of events in this queue</td> </tr> </tbody> </table> +<p>You must call the <code>os_eventq_init()</code> function to initialize an event queue before you can add events to the queue.</p> <h3 id="list-of-functions">List of Functions</h3> -<p>The functions available in event queue feature are:</p> +<p>The functions available in the Event Queue feature are:</p> <table> <thead> <tr> @@ -821,31 +809,35 @@ dynamically, the callback function should free the event. </p> <tbody> <tr> <td><a href="../os_eventq_init/"><code>os_eventq_init</code></a></td> -<td>Initializes the given event queue, making it ready for use.</td> +<td>Initializes an event queue.</td> </tr> <tr> <td><a href="../os_eventq_inited/"><code>os_eventq_inited</code></a></td> -<td>Has the event queue been initialized.</td> +<td>Indicates whether an event queue has been initialized.</td> </tr> <tr> <td><a href="../os_eventq_get/"><code>os_eventq_get</code></a></td> -<td>Fetches the first event from a queue. Task will sleep until something gets queued.</td> +<td>Dequeues an event from the head of an event queue. The calling task blocks (in the <code>sleeping</code> state) when the event queue is empty.</td> </tr> <tr> <td><a href="../os_eventq_put/"><code>os_eventq_put</code></a></td> -<td>Queues an event to tail of the event queue.</td> +<td>Enqueues an event at the tail of an event queue and puts a task waiting for an event on the queue into the <code>ready-to-run</code> state.</td> </tr> <tr> <td><a href="../os_eventq_remove/"><code>os_eventq_remove</code></a></td> -<td>Removes an event which has been placed in a queue.</td> +<td>Removes an event from an event queue.</td> </tr> <tr> -<td><a href="../os_eventq_dflt_set/"><code>os_eventq_dflt_set</code></a></td> -<td>Set the default event queue.</td> +<td><a href="../os_eventq_dflt_get/"><code>os_eventq_dflt_get</code></a></td> +<td>Gets the default event queue.</td> </tr> <tr> -<td><a href="../os_eventq_dflt_get/"><code>os_eventq_dflt_get</code></a></td> -<td>Get the default event queue.</td> +<td><a href="../os_eventq_designate/"><code>os_eventq_designate</code></a></td> +<td>Reassigns a package's current event queue to a new event queue.</td> +</tr> +<tr> +<td><a href="../os_eventq_run/"><code>os_eventq_run</code></a></td> +<td>Wrapper function that dequeues an event from an event queue and calls the callbck function for the event.</td> </tr> </tbody> </table>
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/f245f6aa/develop/os/core_os/event_queue/os_eventq_designate/index.html ---------------------------------------------------------------------- diff --git a/develop/os/core_os/event_queue/os_eventq_designate/index.html b/develop/os/core_os/event_queue/os_eventq_designate/index.html new file mode 100644 index 0000000..8a0d4e9 --- /dev/null +++ b/develop/os/core_os/event_queue/os_eventq_designate/index.html @@ -0,0 +1,870 @@ +<!DOCTYPE html> +<html lang="en"> + <head> + <meta charset="utf-8"> + <meta http-equiv="X-UA-Compatible" content="IE=edge"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + + + <!-- This is broken by doc revisioning. + <link rel="canonical" href="http://mynewt.apache.org/os/core_os/event_queue/os_eventq_designate/";> --> + <link rel="shortcut icon" href="../../../../img/favicon.ico"> + + <title>os_eventq_designate - Apache Mynewt</title> + + <link href="../../../../css/bootstrap-3.0.3.min.css" rel="stylesheet"> + <link rel="stylesheet" href="../../../../css/highlight.css"> + <link href="../../../../css/base.css" rel="stylesheet"> + <link href="../../../../css/custom.css" rel="stylesheet"> + <link href="../../../../css/v2.css" rel="stylesheet"> + <link href="https://fonts.googleapis.com/css?family=Lato"; rel="stylesheet"> + <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.5.0/css/font-awesome.min.css";> + <link href="../../../../extra.css" rel="stylesheet"> + + <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries --> + <!--[if lt IE 9]> + <script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js";></script> + <script src="https://oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js";></script> + <![endif]--> + + + <script> + (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ + (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), + m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) + })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); + + ga('create', 'UA-72162311-1', 'auto'); + ga('send', 'pageview'); + </script> + + </head> + + + <body class="os_eventq_designate"> + + + <div class="container"> + <div class="row v2-main-banner"> + <a class="logo-cell" href="/"> + <img class="logo" src="/img/logo.png"> + </a> + <div class="tagline-cell"> + <h4 class="tagline">An OS to build, deploy and securely manage billions of devices</h4> + </div> + <div class="news-cell"> + <div class="well"> + <h4>Latest News:</h4> <a href="/download">Apache Mynewt 1.0.0-b1</a> released (Dec 13, 2016) + </div> + </div> + </div> +</div> + + + + + + + + +<nav id="navbar" class="navbar navbar-inverse affix-top" data-spy="affix" data-offset-top="150" role="navigation"> + <div class="container"> + <!-- Collapsed navigation --> + <div class="navbar-header"> + <!-- Expander button --> + <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse"> + <span class="sr-only">Toggle navigation</span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + </button> + + </div> + + <!-- Expanded navigation --> + <div class="navbar-collapse collapse"> + <!-- Main navigation --> + <ul class="nav navbar-nav navbar-right"> + <li + class="" +> + <a href="/"><i class="fa fa-home" style="font-size: larger;"></i></a> + </li> + <li + class="important" +> + <a href="/quick-start/">Quick Start</a> + </li> + <li + class="" +> + <a href="/about/">About</a> + </li> + <li + class="" +> + <a href="/talks/">Talks</a> + </li> + <li + class="active" +> + <a href="/latest/os/introduction">Documentation</a> + </li> + <li + class="" +> + <a href="/download/">Download</a> + </li> + <li + class="" +> + <a href="/community/">Community</a> + </li> + <li + class="" +> + <a href="/events/">Events</a> + </li> + </ul> + + <!-- Search, Navigation and Repo links --> + <ul class="nav navbar-nav navbar-right"> + + </ul> + </div> + </div> +</nav> + + + + <div class="container"> + + <div class="row"> + <div class="col-md-3 v2-sidebar sidebar-container"><div id="docSidebar" class="hidden-print" role="complementary"> + <div class="top"> + <div role="search"> + <form id="rtd-search-form" class="wy-form" action="../../../../search.html" method="get"> + <div class="form-group"> + <input type="text" name="q" class="form-control" placeholder="Search documentation" /> + </div> + </form> + </div> + </div> + <ul class="toc-nav"> + <li class="doc-version"> +<select class="form-control" onchange="if (this.value) window.location.href=this.value"> + + <option + value="/develop/os/introduction" + selected="selected" + > + Version: develop (latest) + </option> + + <option + value="/v0_9_0/os/introduction" + + > + Version: 0.9.0 + </option> + +</select> +</li> + + + + + + + + + + + + + + + + + + + + + + <li ><a href="../../../introduction/">Mynewt Documentation</a> + + + <ul> + + + + + + + + <li ><a href="../../../get_started/get_started/">Basic Setup</a> + + + </li> + + + + + + <li > + <a href="../../../get_started/vocabulary/">Concepts</a> + </li> + + + + + + + + <li ><a href="../../../tutorials/tutorials/">Tutorials</a> + + + </li> + + + + + + + + <li ><a href="../../../os_user_guide/">OS User Guide</a> + + + <ul> + + + + + + + + <li ><a href="../../mynewt_os/">OS Core</a> + + + <ul> + + + + + + + + <li><a href=" + ../../os_started/ +">Functions</a> + + + </li> + + + + + + + + <li ><a href="../../context_switch/context_switch/">Scheduler</a> + + + </li> + + + + + + + + <li ><a href="../../time/os_time/">Time</a> + + + </li> + + + + + + + + <li ><a href="../../task/task/">Tasks</a> + + + </li> + + + + + + + + <li ><a href="../event_queue/">Event Queues</a> + + + <ul> + + + + + + + + <li><a href=" + ../os_eventq_init/ +">Functions</a> + + + <ul> + + + + <li > + <a href="../os_eventq_init/">os_eventq_init</a> + </li> + + + + + + <li > + <a href="../os_eventq_inited/">os_eventq_inited</a> + </li> + + + + + + <li > + <a href="../os_eventq_get/">os_eventq_get</a> + </li> + + + + + + <li > + <a href="../os_eventq_put/">os_eventq_put</a> + </li> + + + + + + <li > + <a href="../os_eventq_remove/">os_eventq_remove</a> + </li> + + + + + + <li > + <a href="../os_eventq_dflt_get/">os_eventq_dflt_get</a> + </li> + + + + + + <li class="active"> + <a href="./">os_eventq_designate</a> + </li> + + + + + + <li > + <a href="../os_eventq_run/">os_eventq_run</a> + </li> + + + + </ul> + + </li> + + + + </ul> + + </li> + + + + + + + + <li ><a href="../../semaphore/semaphore/">Semaphores</a> + + + </li> + + + + + + + + <li ><a href="../../mutex/mutex/">Mutexes</a> + + + </li> + + + + + + + + <li ><a href="../../memory_pool/memory_pool/">Memory Pools</a> + + + </li> + + + + + + + + <li ><a href="../../heap/heap/">Heap</a> + + + </li> + + + + + + + + <li><a href=" + + + ../../mbuf/mbuf/ + +">Memory Buffers</a> + + + </li> + + + + + + + + <li ><a href="../../sanity/sanity/">Sanity</a> + + + </li> + + + + + + + + <li ><a href="../../callout/callout/">Callouts</a> + + + </li> + + + + </ul> + + </li> + + + + + + + + <li ><a href="../../porting/port_os/">Porting to your Platform</a> + + + </li> + + + + + + + + <li ><a href="../../../modules/console/console/">Console</a> + + + </li> + + + + + + + + <li ><a href="../../../modules/shell/shell/">Shell</a> + + + </li> + + + + + + + + <li ><a href="../../../modules/split/split/">Split Images</a> + + + </li> + + + + + + + + <li ><a href="../../../modules/bootloader/bootloader/">Bootloader</a> + + + </li> + + + + + + + + <li><a href=" + + + ../../../modules/fs/fs/fs/ + +">File System</a> + + + </li> + + + + + + + + <li ><a href="../../../modules/hal/hal/">Hardware Abstraction Layer</a> + + + </li> + + + + + + + + <li ><a href="../../../modules/drivers/driver/">Drivers</a> + + + </li> + + + + + + + + <li ><a href="../../../modules/testutil/testutil/">Test Utilities</a> + + + </li> + + + + + + + + <li ><a href="../../../modules/devmgmt/newtmgr/">Device Management with Newt Manager</a> + + + </li> + + + + + + + + <li ><a href="../../../modules/imgmgr/imgmgr/">Image Manager</a> + + + </li> + + + + + + <li > + <a href="../../../modules/baselibc/">Baselibc library</a> + </li> + + + + + + + + <li ><a href="../../../modules/elua/elua/">Embedded Lua</a> + + + </li> + + + + + + + + <li ><a href="../../../modules/json/json/">JSON</a> + + + </li> + + + + + + + + <li ><a href="../../../modules/fcb/fcb/">Flash Circular Buffer</a> + + + </li> + + + + + + + + <li ><a href="../../../modules/stats/stats/">Stats</a> + + + </li> + + + + + + + + <li ><a href="../../../modules/logs/logs/">Logs</a> + + + </li> + + + + + + + + <li ><a href="../../../modules/sysinitconfig/sysinitconfig/">System Configuration And Initialization</a> + + + </li> + + + + </ul> + + </li> + + + + + + + + <li><a href=" + ../../../../network/ble/ble_intro/ +">BLE User Guide</a> + + + </li> + + + + + + + + <li ><a href="../../../../newt/newt_intro/">Newt Tool Guide</a> + + + </li> + + + + + + + + <li ><a href="../../../../newtmgr/overview/">Newt Manager Guide</a> + + + </li> + + + + </ul> + + </li> + + + + + + + + <li><a href=" + ../../../../faq/how_to_edit_docs/ +">Appendix</a> + + + </li> + + + + </ul> +</div></div> + + <div class="col-md-9" role="main"> + <div class="doc-header"> + <div role="navigation" aria-label="breadcrumbs navigation"> + <ul class="wy-breadcrumbs pull-right"> + <li><a href="/develop/os/introduction">Docs</a></li> + + + + <li>» <a href="../event_queue/">Event Queues</a></li> + + + + <li>» <a href="../os_eventq_init/">Functions</a></li> + + + + <li>» os_eventq_designate</li> + + + + </ul> +</div> + </div> + + <h2 id="os_eventq_designate"><font color="F2853F" style="font-size:24pt"> os_eventq_designate</font></h2> +<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"> <span style="color: #A90D91">void</span> + <span style="color: #000000">os_eventq_designate</span>(<span style="color: #A90D91">struct</span> <span style="color: #000000">os_eventq</span> <span style="color: #000000">**cur_evq</span>, <span style="color: #A90D91">struct</span> <span style="color: #000000">os_eventq</span> <span style="color: #000000">*new_evq</span>, <span style="color: #A90D91">struct</span> <span style="color: #000000">os_event</span> <span style="color: #000000">*start_ev</span>) +</pre></div> + + +<p>Reassigns a package's current event queue pointer to point to a new event queue. If a startup event +is specified, the event is added to the new event queue and removed from the current event queue.</p> +<h4 id="arguments">Arguments</h4> +<table> +<thead> +<tr> +<th>Arguments</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td><code>cur_evq</code></td> +<td>Current event queue pointer to reassign</td> +</tr> +<tr> +<td><code>new_evq</code></td> +<td>New event queue to use for the package</td> +</tr> +<tr> +<td><code>start_ev</code></td> +<td>Start event to add to the new event queue</td> +</tr> +</tbody> +</table> +<h4 id="returned-values">Returned values</h4> +<p>None</p> +<h4 id="notes">Notes</h4> +<h4 id="example">Example</h4> +<p><Add text to set up the context for the example here></p> +<p>This example shows the <code>mgmt_evq_set()</code> function that the <code>mgmt/newtmgr</code> package implements. The function +allows an application to specify an event queue for <code>newtmgr</code> to use. The <code>mgmt_evq_set()</code> function calls the <code>os_eventq_designate()</code> function to reassign the <code>nmgr_evq</code> to the event queue that the application specifies. </p> +<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">void</span> +<span style="color: #000000">mgmt_evq_set</span>(<span style="color: #A90D91">struct</span> <span style="color: #000000">os_eventq</span> <span style="color: #000000">*evq</span>) +{ + <span style="color: #000000">os_eventq_designate</span>(<span style="color: #000000">&nmgr_evq</span>, <span style="color: #000000">evq</span>, <span style="color: #A90D91">NULL</span>); +} +</pre></div> + + <div class="row"> + + + + +<ul class="nav nav-pills" style="margin-bottom: 10px"> + <li> + + <a href=../os_eventq_dflt_get/> + <span class="fa fa-arrow-left"></span> + Previous: os_eventq_dflt_get + </a> + + </li> + <li class="pull-right"> + + <a href=../os_eventq_run/> + Next: os_eventq_run + <span class="fa fa-arrow-right"></span> + </a> + + </li> +</ul> + </div> + <footer class="row"> + <div class="col-xs-12"> + + <p class="copyright">Apache Mynewt (incubating) is available under Apache License, version 2.0.</p> + + </div> + <div class="col-xs-12"> + <div class="logos"> + <img src="/img/asf_logo_wide_small.png" alt="Apache" title="Apache"> + <small class="footnote"> + MyNewt is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the Apache Incubator. Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF. + </small> + <img src="/img/egg-logo2.png" alt="Apache Incubator" title="Apache Incubator"> + </div> + </div> +</footer> + </div> + </div> + + + </div> + + <script src="../../../../js/jquery-1.10.2.min.js"></script> + <script src="../../../../js/bootstrap-3.0.3.min.js"></script> + <script src="../../../../js/highlight.pack.js"></script> + <script src="../../../../js/base.js"></script> + <script src="../../../../js/custom.js"></script> + + </body> +</html> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/f245f6aa/develop/os/core_os/event_queue/os_eventq_dflt_get/index.html ---------------------------------------------------------------------- diff --git a/develop/os/core_os/event_queue/os_eventq_dflt_get/index.html b/develop/os/core_os/event_queue/os_eventq_dflt_get/index.html index 52c268e..2d057d6 100644 --- a/develop/os/core_os/event_queue/os_eventq_dflt_get/index.html +++ b/develop/os/core_os/event_queue/os_eventq_dflt_get/index.html @@ -360,16 +360,24 @@ + <li class="active"> + <a href="./">os_eventq_dflt_get</a> + </li> + + + + + <li > - <a href="../os_eventq_dflt_set/">os_eventq_dflt_set</a> + <a href="../os_eventq_designate/">os_eventq_designate</a> </li> - <li class="active"> - <a href="./">os_eventq_dflt_get</a> + <li > + <a href="../os_eventq_run/">os_eventq_run</a> </li> @@ -767,25 +775,25 @@ </pre></div> -<p>Get the default event queue that was set</p> +<p>Gets the OS default event queue that Mynewt creates at startup.</p> <h4 id="arguments">Arguments</h4> <p>None</p> <h4 id="returned-values">Returned values</h4> -<p><code>struct os_eventq *</code> A pointer to the default event queue, if set. </p> +<p><code>struct os_eventq *</code>: Pointer to OS the default event queue. </p> <h4 id="notes">Notes</h4> <p>None</p> <h4 id="example">Example</h4> -<p><Add text to set up the context for the example here> -This checks the default event queue and sets it if not already set.</p> -<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">struct</span> <span style="color: #000000">os_eventq</span> <span style="color: #000000">g_my_evq</span>; - -<span style="color: #A90D91">int</span> -<span style="color: #000000">event_q_check</span>() -{ - <span style="color: #A90D91">if</span>(<span style="color: #000000">os_eventq_dflt_get</span>() <span style="color: #000000">==</span> <span style="color: #A90D91">NULL</span>) - { - <span style="color: #000000">os_eventq_dflt_set</span>(<span style="color: #000000">g_my_evq</span>); - } +<p><Add text to set up the context for the example here></p> +<p>This example shows an application's <code>main()</code> function processing events from the OS default event queue.</p> +<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">void</span> <span style="color: #000000">main</span>(<span style="color: #A90D91">int</span> <span style="color: #000000">argc</span>, <span style="color: #A90D91">char</span><span style="color: #000000">**argv</span>) +{ + <span style="color: #000000">sysinit</span>(); + + ... + + <span style="color: #A90D91">while</span> (<span style="color: #1C01CE">1</span>) { + <span style="color: #000000">os_eventq_run</span>(<span style="color: #000000">os_eventq_dflt_get</span>()); + } } </pre></div> @@ -798,16 +806,16 @@ This checks the default event queue and sets it if not already set.</p> <ul class="nav nav-pills" style="margin-bottom: 10px"> <li> - <a href=../os_eventq_dflt_set/> + <a href=../os_eventq_remove/> <span class="fa fa-arrow-left"></span> - Previous: os_eventq_dflt_set + Previous: os_eventq_remove </a> </li> <li class="pull-right"> - <a href=../../semaphore/semaphore/> - Next: Semaphores + <a href=../os_eventq_designate/> + Next: os_eventq_designate <span class="fa fa-arrow-right"></span> </a> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/f245f6aa/develop/os/core_os/event_queue/os_eventq_dflt_set/index.html ---------------------------------------------------------------------- diff --git a/develop/os/core_os/event_queue/os_eventq_dflt_set/index.html b/develop/os/core_os/event_queue/os_eventq_dflt_set/index.html deleted file mode 100644 index d0e421a..0000000 --- a/develop/os/core_os/event_queue/os_eventq_dflt_set/index.html +++ /dev/null @@ -1,860 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta charset="utf-8"> - <meta http-equiv="X-UA-Compatible" content="IE=edge"> - <meta name="viewport" content="width=device-width, initial-scale=1.0"> - - - <!-- This is broken by doc revisioning. - <link rel="canonical" href="http://mynewt.apache.org/os/core_os/event_queue/os_eventq_dflt_set/";> --> - <link rel="shortcut icon" href="../../../../img/favicon.ico"> - - <title>os_eventq_dflt_set - Apache Mynewt</title> - - <link href="../../../../css/bootstrap-3.0.3.min.css" rel="stylesheet"> - <link rel="stylesheet" href="../../../../css/highlight.css"> - <link href="../../../../css/base.css" rel="stylesheet"> - <link href="../../../../css/custom.css" rel="stylesheet"> - <link href="../../../../css/v2.css" rel="stylesheet"> - <link href="https://fonts.googleapis.com/css?family=Lato"; rel="stylesheet"> - <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.5.0/css/font-awesome.min.css";> - <link href="../../../../extra.css" rel="stylesheet"> - - <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries --> - <!--[if lt IE 9]> - <script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js";></script> - <script src="https://oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js";></script> - <![endif]--> - - - <script> - (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ - (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), - m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) - })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); - - ga('create', 'UA-72162311-1', 'auto'); - ga('send', 'pageview'); - </script> - - </head> - - - <body class="os_eventq_dflt_set"> - - - <div class="container"> - <div class="row v2-main-banner"> - <a class="logo-cell" href="/"> - <img class="logo" src="/img/logo.png"> - </a> - <div class="tagline-cell"> - <h4 class="tagline">An OS to build, deploy and securely manage billions of devices</h4> - </div> - <div class="news-cell"> - <div class="well"> - <h4>Latest News:</h4> <a href="/download">Apache Mynewt 1.0.0-b1</a> released (Dec 13, 2016) - </div> - </div> - </div> -</div> - - - - - - - - -<nav id="navbar" class="navbar navbar-inverse affix-top" data-spy="affix" data-offset-top="150" role="navigation"> - <div class="container"> - <!-- Collapsed navigation --> - <div class="navbar-header"> - <!-- Expander button --> - <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse"> - <span class="sr-only">Toggle navigation</span> - <span class="icon-bar"></span> - <span class="icon-bar"></span> - <span class="icon-bar"></span> - </button> - - </div> - - <!-- Expanded navigation --> - <div class="navbar-collapse collapse"> - <!-- Main navigation --> - <ul class="nav navbar-nav navbar-right"> - <li - class="" -> - <a href="/"><i class="fa fa-home" style="font-size: larger;"></i></a> - </li> - <li - class="important" -> - <a href="/quick-start/">Quick Start</a> - </li> - <li - class="" -> - <a href="/about/">About</a> - </li> - <li - class="" -> - <a href="/talks/">Talks</a> - </li> - <li - class="active" -> - <a href="/latest/os/introduction">Documentation</a> - </li> - <li - class="" -> - <a href="/download/">Download</a> - </li> - <li - class="" -> - <a href="/community/">Community</a> - </li> - <li - class="" -> - <a href="/events/">Events</a> - </li> - </ul> - - <!-- Search, Navigation and Repo links --> - <ul class="nav navbar-nav navbar-right"> - - </ul> - </div> - </div> -</nav> - - - - <div class="container"> - - <div class="row"> - <div class="col-md-3 v2-sidebar sidebar-container"><div id="docSidebar" class="hidden-print" role="complementary"> - <div class="top"> - <div role="search"> - <form id="rtd-search-form" class="wy-form" action="../../../../search.html" method="get"> - <div class="form-group"> - <input type="text" name="q" class="form-control" placeholder="Search documentation" /> - </div> - </form> - </div> - </div> - <ul class="toc-nav"> - <li class="doc-version"> -<select class="form-control" onchange="if (this.value) window.location.href=this.value"> - - <option - value="/develop/os/introduction" - selected="selected" - > - Version: develop (latest) - </option> - - <option - value="/v0_9_0/os/introduction" - - > - Version: 0.9.0 - </option> - -</select> -</li> - - - - - - - - - - - - - - - - - - - - - - <li ><a href="../../../introduction/">Mynewt Documentation</a> - - - <ul> - - - - - - - - <li ><a href="../../../get_started/get_started/">Basic Setup</a> - - - </li> - - - - - - <li > - <a href="../../../get_started/vocabulary/">Concepts</a> - </li> - - - - - - - - <li ><a href="../../../tutorials/tutorials/">Tutorials</a> - - - </li> - - - - - - - - <li ><a href="../../../os_user_guide/">OS User Guide</a> - - - <ul> - - - - - - - - <li ><a href="../../mynewt_os/">OS Core</a> - - - <ul> - - - - - - - - <li><a href=" - ../../os_started/ -">Functions</a> - - - </li> - - - - - - - - <li ><a href="../../context_switch/context_switch/">Scheduler</a> - - - </li> - - - - - - - - <li ><a href="../../time/os_time/">Time</a> - - - </li> - - - - - - - - <li ><a href="../../task/task/">Tasks</a> - - - </li> - - - - - - - - <li ><a href="../event_queue/">Event Queues</a> - - - <ul> - - - - - - - - <li><a href=" - ../os_eventq_init/ -">Functions</a> - - - <ul> - - - - <li > - <a href="../os_eventq_init/">os_eventq_init</a> - </li> - - - - - - <li > - <a href="../os_eventq_inited/">os_eventq_inited</a> - </li> - - - - - - <li > - <a href="../os_eventq_get/">os_eventq_get</a> - </li> - - - - - - <li > - <a href="../os_eventq_put/">os_eventq_put</a> - </li> - - - - - - <li > - <a href="../os_eventq_remove/">os_eventq_remove</a> - </li> - - - - - - <li class="active"> - <a href="./">os_eventq_dflt_set</a> - </li> - - - - - - <li > - <a href="../os_eventq_dflt_get/">os_eventq_dflt_get</a> - </li> - - - - </ul> - - </li> - - - - </ul> - - </li> - - - - - - - - <li ><a href="../../semaphore/semaphore/">Semaphores</a> - - - </li> - - - - - - - - <li ><a href="../../mutex/mutex/">Mutexes</a> - - - </li> - - - - - - - - <li ><a href="../../memory_pool/memory_pool/">Memory Pools</a> - - - </li> - - - - - - - - <li ><a href="../../heap/heap/">Heap</a> - - - </li> - - - - - - - - <li><a href=" - - - ../../mbuf/mbuf/ - -">Memory Buffers</a> - - - </li> - - - - - - - - <li ><a href="../../sanity/sanity/">Sanity</a> - - - </li> - - - - - - - - <li ><a href="../../callout/callout/">Callouts</a> - - - </li> - - - - </ul> - - </li> - - - - - - - - <li ><a href="../../porting/port_os/">Porting to your Platform</a> - - - </li> - - - - - - - - <li ><a href="../../../modules/console/console/">Console</a> - - - </li> - - - - - - - - <li ><a href="../../../modules/shell/shell/">Shell</a> - - - </li> - - - - - - - - <li ><a href="../../../modules/split/split/">Split Images</a> - - - </li> - - - - - - - - <li ><a href="../../../modules/bootloader/bootloader/">Bootloader</a> - - - </li> - - - - - - - - <li><a href=" - - - ../../../modules/fs/fs/fs/ - -">File System</a> - - - </li> - - - - - - - - <li ><a href="../../../modules/hal/hal/">Hardware Abstraction Layer</a> - - - </li> - - - - - - - - <li ><a href="../../../modules/drivers/driver/">Drivers</a> - - - </li> - - - - - - - - <li ><a href="../../../modules/testutil/testutil/">Test Utilities</a> - - - </li> - - - - - - - - <li ><a href="../../../modules/devmgmt/newtmgr/">Device Management with Newt Manager</a> - - - </li> - - - - - - - - <li ><a href="../../../modules/imgmgr/imgmgr/">Image Manager</a> - - - </li> - - - - - - <li > - <a href="../../../modules/baselibc/">Baselibc library</a> - </li> - - - - - - - - <li ><a href="../../../modules/elua/elua/">Embedded Lua</a> - - - </li> - - - - - - - - <li ><a href="../../../modules/json/json/">JSON</a> - - - </li> - - - - - - - - <li ><a href="../../../modules/fcb/fcb/">Flash Circular Buffer</a> - - - </li> - - - - - - - - <li ><a href="../../../modules/stats/stats/">Stats</a> - - - </li> - - - - - - - - <li ><a href="../../../modules/logs/logs/">Logs</a> - - - </li> - - - - - - - - <li ><a href="../../../modules/sysinitconfig/sysinitconfig/">System Configuration And Initialization</a> - - - </li> - - - - </ul> - - </li> - - - - - - - - <li><a href=" - ../../../../network/ble/ble_intro/ -">BLE User Guide</a> - - - </li> - - - - - - - - <li ><a href="../../../../newt/newt_intro/">Newt Tool Guide</a> - - - </li> - - - - - - - - <li ><a href="../../../../newtmgr/overview/">Newt Manager Guide</a> - - - </li> - - - - </ul> - - </li> - - - - - - - - <li><a href=" - ../../../../faq/how_to_edit_docs/ -">Appendix</a> - - - </li> - - - - </ul> -</div></div> - - <div class="col-md-9" role="main"> - <div class="doc-header"> - <div role="navigation" aria-label="breadcrumbs navigation"> - <ul class="wy-breadcrumbs pull-right"> - <li><a href="/develop/os/introduction">Docs</a></li> - - - - <li>» <a href="../event_queue/">Event Queues</a></li> - - - - <li>» <a href="../os_eventq_init/">Functions</a></li> - - - - <li>» os_eventq_dflt_set</li> - - - - </ul> -</div> - </div> - - <h2 id="os_eventq_dflt_set"><font color="F2853F" style="font-size:24pt"> os_eventq_dflt_set</font></h2> -<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"> <span style="color: #A90D91">void</span> - <span style="color: #000000">os_eventq_dflt_set</span>(<span style="color: #A90D91">struct</span> <span style="color: #000000">os_eventq</span> <span style="color: #000000">*evq</span>) -</pre></div> - - -<p>Sets <code>struct os_eventq</code> as the default event queue</p> -<h4 id="arguments">Arguments</h4> -<table> -<thead> -<tr> -<th>Arguments</th> -<th>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td><code>evq</code></td> -<td>Pointer to default event queue to use</td> -</tr> -</tbody> -</table> -<h4 id="returned-values">Returned values</h4> -<p>None</p> -<h4 id="notes">Notes</h4> -<p>Usually done at subsystem init time; before OS has been started, and before interrupts generating events have been enabled.</p> -<h4 id="example">Example</h4> -<p><Add text to set up the context for the example here> -This sets the default event queue used by newtmgr task.</p> -<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">struct</span> <span style="color: #000000">os_eventq</span> <span style="color: #000000">g_nmgr_evq</span>; - -<span style="color: #A90D91">int</span> -<span style="color: #000000">nmgr_task_init</span>(<span style="color: #A90D91">uint8_t</span> <span style="color: #000000">prio</span>, <span style="color: #A90D91">os_stack_t</span> <span style="color: #000000">*stack_ptr</span>, <span style="color: #A90D91">uint16_t</span> <span style="color: #000000">stack_len</span>) -{ - <span style="color: #177500">/* variable declarations here */</span> - - <span style="color: #000000">os_eventq_init</span>(<span style="color: #000000">&g_nmgr_evq</span>); - <span style="color: #000000">os_eventq_dflt_set</span>(<span style="color: #000000">&g_nmgr_evq</span>); - - <span style="color: #177500">/* initialization continues here */</span> -} -</pre></div> - - <div class="row"> - - - - -<ul class="nav nav-pills" style="margin-bottom: 10px"> - <li> - - <a href=../os_eventq_remove/> - <span class="fa fa-arrow-left"></span> - Previous: os_eventq_remove - </a> - - </li> - <li class="pull-right"> - - <a href=../os_eventq_dflt_get/> - Next: os_eventq_dflt_get - <span class="fa fa-arrow-right"></span> - </a> - - </li> -</ul> - </div> - <footer class="row"> - <div class="col-xs-12"> - - <p class="copyright">Apache Mynewt (incubating) is available under Apache License, version 2.0.</p> - - </div> - <div class="col-xs-12"> - <div class="logos"> - <img src="/img/asf_logo_wide_small.png" alt="Apache" title="Apache"> - <small class="footnote"> - MyNewt is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the Apache Incubator. Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF. - </small> - <img src="/img/egg-logo2.png" alt="Apache Incubator" title="Apache Incubator"> - </div> - </div> -</footer> - </div> - </div> - - - </div> - - <script src="../../../../js/jquery-1.10.2.min.js"></script> - <script src="../../../../js/bootstrap-3.0.3.min.js"></script> - <script src="../../../../js/highlight.pack.js"></script> - <script src="../../../../js/base.js"></script> - <script src="../../../../js/custom.js"></script> - - </body> -</html> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/f245f6aa/develop/os/core_os/event_queue/os_eventq_get/index.html ---------------------------------------------------------------------- diff --git a/develop/os/core_os/event_queue/os_eventq_get/index.html b/develop/os/core_os/event_queue/os_eventq_get/index.html index f676073..7736f58 100644 --- a/develop/os/core_os/event_queue/os_eventq_get/index.html +++ b/develop/os/core_os/event_queue/os_eventq_get/index.html @@ -361,7 +361,7 @@ <li > - <a href="../os_eventq_dflt_set/">os_eventq_dflt_set</a> + <a href="../os_eventq_dflt_get/">os_eventq_dflt_get</a> </li> @@ -369,7 +369,15 @@ <li > - <a href="../os_eventq_dflt_get/">os_eventq_dflt_get</a> + <a href="../os_eventq_designate/">os_eventq_designate</a> + </li> + + + + + + <li > + <a href="../os_eventq_run/">os_eventq_run</a> </li> @@ -762,12 +770,13 @@ </div> <h2 id="os_eventq_get"><font color="#F2853F" style="font-size:24pt"> os_eventq_get</font></h2> -<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">void</span> +<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">struct</span> <span style="color: #000000">os_event</span> <span style="color: #000000">*</span> <span style="color: #000000">os_eventq_get</span>(<span style="color: #A90D91">struct</span> <span style="color: #000000">os_eventq</span> <span style="color: #000000">*evq</span>) </pre></div> -<p>Fetches the first event from a queue. Task will sleep until something gets queued.</p> +<p>Dequeues and returns an event from the head of an event queue. When the event queue is empty, +the function puts the task into the <code>sleeping</code> state.</p> <h4 id="arguments">Arguments</h4> <table> <thead> @@ -779,22 +788,27 @@ <tbody> <tr> <td><code>evq</code></td> -<td>Queue to wait on</td> +<td>Event queue to retrieve the event from</td> </tr> </tbody> </table> <h4 id="returned-values">Returned values</h4> -<p>Will return with a pointer to first <code>struct event</code> which is in the queue.</p> +<p>A pointer to the <code>os_event</code> structure for the event dequeued from the queue. </p> <h4 id="notes">Notes</h4> +<p>In most cases, you do not need to call this function directly. You should call the <code>os_eventq_run()</code> wrapper +function that calls this function to retrieve an event and then calls the callback function to process the event. </p> <h4 id="example">Example</h4> -<p>Main loop of an example task.</p> -<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"> <span style="color: #A90D91">while</span> (<span style="color: #1C01CE">1</span>) { - <span style="color: #000000">ev</span> <span style="color: #000000">=</span> <span style="color: #000000">os_eventq_get</span>(<span style="color: #000000">&task1_evq</span>); - <span style="color: #000000">assert</span>(<span style="color: #000000">ev</span>); - <span style="color: #A90D91">if</span> (<span style="color: #000000">ev->ev_type</span> <span style="color: #000000">==</span> <span style="color: #000000">CONS_EV_TYPE</span>) { - <span style="color: #177500">/* XXX do stuff */</span> - } - } +<p>Example of the <code>os_eventq_run()</code> wrapper function that calls this function:</p> +<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">void</span> +<span style="color: #000000">os_eventq_run</span>(<span style="color: #A90D91">struct</span> <span style="color: #000000">os_eventq</span> <span style="color: #000000">*evq</span>) +{ + <span style="color: #A90D91">struct</span> <span style="color: #000000">os_event</span> <span style="color: #000000">*ev</span>; + + <span style="color: #000000">ev</span> <span style="color: #000000">=</span> <span style="color: #000000">os_eventq_get</span>(<span style="color: #000000">evq</span>); + <span style="color: #000000">assert</span>(<span style="color: #000000">ev->ev_cb</span> <span style="color: #000000">!=</span> <span style="color: #A90D91">NULL</span>); + + <span style="color: #000000">ev->ev_cb</span>(<span style="color: #000000">ev</span>); +} </pre></div> <div class="row"> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/f245f6aa/develop/os/core_os/event_queue/os_eventq_init/index.html ---------------------------------------------------------------------- diff --git a/develop/os/core_os/event_queue/os_eventq_init/index.html b/develop/os/core_os/event_queue/os_eventq_init/index.html index 887e3fc..00e88f0 100644 --- a/develop/os/core_os/event_queue/os_eventq_init/index.html +++ b/develop/os/core_os/event_queue/os_eventq_init/index.html @@ -361,7 +361,7 @@ <li > - <a href="../os_eventq_dflt_set/">os_eventq_dflt_set</a> + <a href="../os_eventq_dflt_get/">os_eventq_dflt_get</a> </li> @@ -369,7 +369,15 @@ <li > - <a href="../os_eventq_dflt_get/">os_eventq_dflt_get</a> + <a href="../os_eventq_designate/">os_eventq_designate</a> + </li> + + + + + + <li > + <a href="../os_eventq_run/">os_eventq_run</a> </li> @@ -767,7 +775,7 @@ </pre></div> -<p>Initializes <code>struct os_eventq</code>, making it ready for use.</p> +<p>Initializes an event queue. </p> <h4 id="arguments">Arguments</h4> <table> <thead> @@ -779,27 +787,28 @@ <tbody> <tr> <td><code>evq</code></td> -<td>Pointer to event queue getting initialized</td> +<td>Pointer to the event queue to initialize</td> </tr> </tbody> </table> <h4 id="returned-values">Returned values</h4> <p>None</p> <h4 id="notes">Notes</h4> -<p>Usually done at subsystem init time; before OS has been started, and before interrupts generating events have been enabled.</p> +<p>Called during OS, package, and application initialization and before interrupts generating events have been enabled.</p> <h4 id="example">Example</h4> <p><Add text to set up the context for the example here> -This initializes event queue used by newtmgr task.</p> -<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">struct</span> <span style="color: #000000">os_eventq</span> <span style="color: #000000">g_nmgr_evq</span>; +This example shows the <code>app/bletest</code> application initializing the <code>g_bletest_evq</code> event queue.</p> +<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">struct</span> <span style="color: #000000">os_eventq</span> <span style="color: #000000">g_bletest_evq</span>; <span style="color: #A90D91">int</span> -<span style="color: #000000">nmgr_task_init</span>(<span style="color: #A90D91">uint8_t</span> <span style="color: #000000">prio</span>, <span style="color: #A90D91">os_stack_t</span> <span style="color: #000000">*stack_ptr</span>, <span style="color: #A90D91">uint16_t</span> <span style="color: #000000">stack_len</span>) +<span style="color: #000000">main</span>(<span style="color: #A90D91">void</span>) { <span style="color: #177500">/* variable declarations here */</span> - <span style="color: #000000">os_eventq_init</span>(<span style="color: #000000">&g_nmgr_evq</span>); + <span style="color: #000000">os_eventq_init</span>(<span style="color: #000000">&g_bletest_evq</span>); <span style="color: #177500">/* initialization continues here */</span> + } </pre></div> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/f245f6aa/develop/os/core_os/event_queue/os_eventq_inited/index.html ---------------------------------------------------------------------- diff --git a/develop/os/core_os/event_queue/os_eventq_inited/index.html b/develop/os/core_os/event_queue/os_eventq_inited/index.html index 5231bb0..3eeb224 100644 --- a/develop/os/core_os/event_queue/os_eventq_inited/index.html +++ b/develop/os/core_os/event_queue/os_eventq_inited/index.html @@ -361,7 +361,7 @@ <li > - <a href="../os_eventq_dflt_set/">os_eventq_dflt_set</a> + <a href="../os_eventq_dflt_get/">os_eventq_dflt_get</a> </li> @@ -369,7 +369,15 @@ <li > - <a href="../os_eventq_dflt_get/">os_eventq_dflt_get</a> + <a href="../os_eventq_designate/">os_eventq_designate</a> + </li> + + + + + + <li > + <a href="../os_eventq_run/">os_eventq_run</a> </li> @@ -767,7 +775,7 @@ </pre></div> -<p>Check if event queue <code>const struct os_eventq</code> is ready for use.</p> +<p>Indicates whether an event queue has been initialized.</p> <h4 id="arguments">Arguments</h4> <table> <thead> @@ -779,18 +787,21 @@ <tbody> <tr> <td><code>evq</code></td> -<td>Pointer to event queue to check</td> +<td>Pointer to the event queue to check</td> </tr> </tbody> </table> <h4 id="returned-values">Returned values</h4> -<p><code>0</code> if event queue is ready</p> +<ul> +<li>1 if the event queue has been initialized and ready for use.</li> +<li>0 if the event queue has not been initialized.</li> +</ul> <h4 id="notes">Notes</h4> -<p>If an event queue was properly initialized (and the proper checks were done at initialization) -this check is not needed prior to using an event queue.</p> +<p>You do not need to call this function prior to using an event queue if you have called the <code>os_eventq_init()</code> function +to initialize the queue.</p> <h4 id="example">Example</h4> <p><Add text to set up the context for the example here> -This checks an event queue before using it.</p> +This example checks whether an event queue has been initialized.</p> <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">struct</span> <span style="color: #000000">os_eventq</span> <span style="color: #000000">g_my_evq</span>; <span style="color: #A90D91">int</span> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/f245f6aa/develop/os/core_os/event_queue/os_eventq_put/index.html ---------------------------------------------------------------------- diff --git a/develop/os/core_os/event_queue/os_eventq_put/index.html b/develop/os/core_os/event_queue/os_eventq_put/index.html index b3969d3..1145c5f 100644 --- a/develop/os/core_os/event_queue/os_eventq_put/index.html +++ b/develop/os/core_os/event_queue/os_eventq_put/index.html @@ -361,7 +361,7 @@ <li > - <a href="../os_eventq_dflt_set/">os_eventq_dflt_set</a> + <a href="../os_eventq_dflt_get/">os_eventq_dflt_get</a> </li> @@ -369,7 +369,15 @@ <li > - <a href="../os_eventq_dflt_get/">os_eventq_dflt_get</a> + <a href="../os_eventq_designate/">os_eventq_designate</a> + </li> + + + + + + <li > + <a href="../os_eventq_run/">os_eventq_run</a> </li> @@ -767,7 +775,7 @@ </pre></div> -<p>Queues an event to the tail of the event queue.</p> +<p>Enqueues an event onto the tail of an event queue. It puts a task, if any, that is in the <code>sleeping</code> state waiting for an event into the <code>ready-to-run</code> state.</p> <h4 id="arguments">Arguments</h4> <table> <thead> @@ -779,11 +787,11 @@ <tbody> <tr> <td><code>evq</code></td> -<td>Queue where event is being placed</td> +<td>Event queue to add the event to</td> </tr> <tr> <td><code>ev</code></td> -<td>Event which is being queued</td> +<td>Event to enqueue</td> </tr> </tbody> </table> @@ -791,20 +799,51 @@ <p>N/A</p> <h4 id="example">Example</h4> <p><Add text to set up the context for the example here> -This is used to pass info about an event to a task handling it.</p> -<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"> <span style="color: #177500">/* Get an event structure off the queue */</span> - <span style="color: #000000">ev</span> <span style="color: #000000">=</span> (<span style="color: #A90D91">struct</span> <span style="color: #000000">os_event</span> <span style="color: #000000">*</span>)<span style="color: #000000">os_memblock_get</span>(<span style="color: #000000">&g_hci_os_event_pool</span>); - <span style="color: #A90D91">if</span> (<span style="color: #000000">!ev</span>) { - <span style="color: #000000">err</span> <span style="color: #000000">=</span> <span style="color: #000000">os_memblock_put</span>(<span style="color: #000000">&g_hci_cmd_pool</span>, <span style="color: #000000">hci_ev</span>); - <span style="color: #000000">assert</span>(<span style="color: #000000">err</span> <span style="color: #000000">==</span> <span style="color: #000000">OS_OK</span>); - <span style="color: #A90D91">return</span> <span style="color: #000000">-</span><span style="color: #1C01CE">1</span>; +This example shows the ble host adding a host controller interface event to the <code>ble_hs_eventq</code> event queue.</p> +<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #177500">/* Returns the ble_hs_eventq */</span> +<span style="color: #A90D91">static</span> <span style="color: #A90D91">struct</span> <span style="color: #000000">os_eventq</span> <span style="color: #000000">*</span> +<span style="color: #000000">ble_hs_evq_get</span>(<span style="color: #A90D91">void</span>) +{ + <span style="color: #A90D91">return</span> <span style="color: #000000">ble_hs_evq</span>; +} + +<span style="color: #177500">/* Event callback function */</span> +<span style="color: #A90D91">static</span> <span style="color: #A90D91">void</span> +<span style="color: #000000">ble_hs_event_rx_hci_ev</span>(<span style="color: #A90D91">struct</span> <span style="color: #000000">os_event</span> <span style="color: #000000">*ev</span>) +{ + <span style="color: #A90D91">uint8_t</span> <span style="color: #000000">*hci_evt</span>; + <span style="color: #A90D91">int</span> <span style="color: #000000">rc</span>; + + <span style="color: #000000">hci_evt</span> <span style="color: #000000">=</span> <span style="color: #000000">ev->ev_arg</span>; + <span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">os_memblock_put</span>(<span style="color: #000000">&ble_hs_hci_ev_pool</span>, <span style="color: #000000">ev</span>); + <span style="color: #000000">BLE_HS_DBG_ASSERT_EVAL</span>(<span style="color: #000000">rc</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span>); + + <span style="color: #000000">ble_hs_hci_evt_process</span>(<span style="color: #000000">hci_evt</span>); +} + +<span style="color: #A90D91">void</span> +<span style="color: #000000">ble_hs_enqueue_hci_event</span>(<span style="color: #A90D91">uint8_t</span> <span style="color: #000000">*hci_evt</span>) +{ + <span style="color: #A90D91">struct</span> <span style="color: #000000">os_event</span> <span style="color: #000000">*ev</span>; + + <span style="color: #177500">/* Allocates memory for the event */</span> + <span style="color: #000000">ev</span> <span style="color: #000000">=</span> <span style="color: #000000">os_memblock_get</span>(<span style="color: #000000">&ble_hs_hci_ev_pool</span>); + + <span style="color: #A90D91">if</span> (<span style="color: #000000">ev</span> <span style="color: #000000">==</span> <span style="color: #A90D91">NULL</span>) { + <span style="color: #000000">ble_hci_trans_buf_free</span>(<span style="color: #000000">hci_evt</span>); + } <span style="color: #A90D91">else</span> { + <span style="color: #177500">/* </span> +<span style="color: #177500"> * Initializes the event with the ble_hs_event_rx_hci_ev callback function </span> +<span style="color: #177500"> * and the hci_evt data for the callback function to use. </span> +<span style="color: #177500"> */</span> + <span style="color: #000000">ev->ev_queued</span> <span style="color: #000000">=</span> <span style="color: #1C01CE">0</span>; + <span style="color: #000000">ev->ev_cb</span> <span style="color: #000000">=</span> <span style="color: #000000">ble_hs_event_rx_hci_ev</span>; + <span style="color: #000000">ev->ev_arg</span> <span style="color: #000000">=</span> <span style="color: #000000">hci_evt</span>; + + <span style="color: #177500">/* Enqueues the event on the ble_hs_evq */</span> + <span style="color: #000000">os_eventq_put</span>(<span style="color: #000000">ble_hs_evq_get</span>(), <span style="color: #000000">ev</span>); } - - <span style="color: #177500">/* Fill out the event and post to Link Layer */</span> - <span style="color: #000000">ev->ev_queued</span> <span style="color: #000000">=</span> <span style="color: #1C01CE">0</span>; - <span style="color: #000000">ev->ev_type</span> <span style="color: #000000">=</span> <span style="color: #000000">BLE_HOST_HCI_EVENT_CTLR_EVENT</span>; - <span style="color: #000000">ev->ev_arg</span> <span style="color: #000000">=</span> <span style="color: #000000">hci_ev</span>; - <span style="color: #000000">os_eventq_put</span>(<span style="color: #000000">&ble_hs_evq</span>, <span style="color: #000000">ev</span>); +} </pre></div> <div class="row"> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/f245f6aa/develop/os/core_os/event_queue/os_eventq_remove/index.html ---------------------------------------------------------------------- diff --git a/develop/os/core_os/event_queue/os_eventq_remove/index.html b/develop/os/core_os/event_queue/os_eventq_remove/index.html index 1aa4c03..748cf55 100644 --- a/develop/os/core_os/event_queue/os_eventq_remove/index.html +++ b/develop/os/core_os/event_queue/os_eventq_remove/index.html @@ -361,7 +361,7 @@ <li > - <a href="../os_eventq_dflt_set/">os_eventq_dflt_set</a> + <a href="../os_eventq_dflt_get/">os_eventq_dflt_get</a> </li> @@ -369,7 +369,15 @@ <li > - <a href="../os_eventq_dflt_get/">os_eventq_dflt_get</a> + <a href="../os_eventq_designate/">os_eventq_designate</a> + </li> + + + + + + <li > + <a href="../os_eventq_run/">os_eventq_run</a> </li> @@ -767,7 +775,7 @@ </pre></div> -<p>Removes an event which has been placed in a queue.</p> +<p>Removes an event from an event queue.</p> <h4 id="arguments">Arguments</h4> <table> <thead> @@ -779,11 +787,11 @@ <tbody> <tr> <td><code>evq</code></td> -<td>Queue where event is being removed from</td> +<td>Event queue to remove the event from</td> </tr> <tr> <td><code>ev</code></td> -<td>Event which is being removed</td> +<td>Event to remove</td> </tr> </tbody> </table> @@ -792,10 +800,26 @@ <h4 id="notes">Notes</h4> <h4 id="example">Example</h4> <p><Add text to set up the context for the example here> -This is from <code>os_callout_stop()</code>. User wants to stop a callout from getting passed to a task. If the event has already been queued, then remove it before it is seen.</p> -<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"> <span style="color: #A90D91">if</span> (<span style="color: #000000">c->c_evq</span>) { +This example from the <code>os_callout_stop()</code> function shows how to remove a callout event from an event queue. It removes +the event from the queue if the event is queued.</p> +<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">void</span> +<span style="color: #000000">os_callout_stop</span>(<span style="color: #A90D91">struct</span> <span style="color: #000000">os_callout</span> <span style="color: #000000">*c</span>) +{ + <span style="color: #A90D91">os_sr_t</span> <span style="color: #000000">sr</span>; + + <span style="color: #000000">OS_ENTER_CRITICAL</span>(<span style="color: #000000">sr</span>); + + <span style="color: #A90D91">if</span> (<span style="color: #000000">os_callout_queued</span>(<span style="color: #000000">c</span>)) { + <span style="color: #000000">TAILQ_REMOVE</span>(<span style="color: #000000">&g_callout_list</span>, <span style="color: #000000">c</span>, <span style="color: #000000">c_next</span>); + <span style="color: #000000">c->c_next</span>.<span style="color: #000000">tqe_prev</span> <span style="color: #000000">=</span> <span style="color: #A90D91">NULL</span>; + } + + <span style="color: #A90D91">if</span> (<span style="color: #000000">c->c_evq</span>) { <span style="color: #000000">os_eventq_remove</span>(<span style="color: #000000">c->c_evq</span>, <span style="color: #000000">&c->c_ev</span>); } + + <span style="color: #000000">OS_EXIT_CRITICAL</span>(<span style="color: #000000">sr</span>); +} </pre></div> <div class="row"> @@ -814,8 +838,8 @@ This is from <code>os_callout_stop()</code>. User wants to stop a callout from g </li> <li class="pull-right"> - <a href=../os_eventq_dflt_set/> - Next: os_eventq_dflt_set + <a href=../os_eventq_dflt_get/> + Next: os_eventq_dflt_get <span class="fa fa-arrow-right"></span> </a>
