| |
| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="utf-8"> |
| <meta name="viewport" content="width=device-width, initial-scale=1"> |
| <meta name="description" content=""> |
| <meta name="author" content=""> |
| |
| <title>Apache Celix Events / Apache Celix</title> |
| |
| |
| <link rel="icon" href="/assets/img/favicon.ico"> |
| |
| |
| <link href="/assets/css/bootstrap.min.css" rel="stylesheet"> |
| |
| |
| <link href="/assets/css/style.css" rel="stylesheet"> |
| |
| |
| <script> |
| var _paq = window._paq = window._paq || []; |
| |
| _paq.push(['disableCookies']); |
| |
| _paq.push(['trackPageView']); |
| _paq.push(['enableLinkTracking']); |
| (function() { |
| var u="https://analytics.apache.org/"; |
| _paq.push(['setTrackerUrl', u+'matomo.php']); |
| _paq.push(['setSiteId', '9']); |
| var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0]; |
| g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s); |
| })(); |
| </script> |
| |
| |
| </head> |
| <body class="light-grey"> |
| |
| <a href="https://github.com/apache/celix" class="github-ribbon"> |
| <img src="/assets/img/forkme_right_red_aa0000.png" alt="Fork me on GitHub"> |
| </a> |
| |
| |
| <nav class="navbar navbar-expand-lg navbar-dark bg-primary fixed-top"> |
| <div class="container"> |
| <a class="navbar-brand" href="/"> |
| <img src="/assets/img/celix-white.svg" height="40" class="d-inline-block align-top" alt="Celix Logo"> |
| </a> |
| <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarResponsive" aria-controls="navbarResponsive" aria-expanded="false" aria-label="Toggle navigation"> |
| <span class="navbar-toggler-icon"></span> |
| </button> |
| <div class="collapse navbar-collapse" id="navbarResponsive"> |
| <ul class="navbar-nav ml-auto"> |
| <li class="nav-item"> |
| <a class="nav-link" href="/">Home</a> |
| </li> |
| <li class="nav-item"> |
| <a class="nav-link" href="/download.cgi">Download</a> |
| </li> |
| <li class="nav-item dropdown active"> |
| <a class="nav-link dropdown-toggle" href="#" id="ddDocs" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> |
| Docs |
| </a> |
| <div class="dropdown-menu" aria-labelledby="ddDocs"> |
| <a class="dropdown-item" href="/docs/2.4.0/docs.html">2.4.0 (latest)</a> |
| <a class="dropdown-item" href="/docs/2.3.0/docs.html">2.3.0</a> |
| <a class="dropdown-item" href="/docs/2.2.1/docs.html">2.2.1</a> |
| <a class="dropdown-item" href="/docs/2.1.0/docs.html">2.1.0</a> |
| </div> |
| </li> |
| <li class="nav-item dropdown"> |
| <a class="nav-link dropdown-toggle" href="#" id="ddContributing" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> |
| Contributing |
| </a> |
| <div class="dropdown-menu" aria-labelledby="ddContributing"> |
| <a class="dropdown-item" href="/contributing/youatcelix.html">You at Celix</a> |
| <a class="dropdown-item" href="/contributing/submitting-patches.html">Submitting patches</a> |
| <a class="dropdown-item" href="/contributing/source-and-builds.html">Source code and builds</a> |
| <hr> |
| <a class="dropdown-item" href="/contributing/releasing.html">Releasing</a> |
| <a class="dropdown-item" href="/contributing/volunteers.html">Volunteers</a> |
| <a class="dropdown-item" href="https://whimsy.apache.org/board/minutes/Celix.html">Board Reports</a> |
| </div> |
| </li> |
| <li class="nav-item dropdown"> |
| <a class="nav-link dropdown-toggle" href="#" id="ddSupport" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> |
| Support |
| </a> |
| <div class="dropdown-menu" aria-labelledby="ddSupport"> |
| <a class="dropdown-item" href="/support/mailing-list.html">Mailing Lists</a> |
| <a class="dropdown-item" href="/support/issue-tracking.html">Issue Tracking</a> |
| </div> |
| </li> |
| <li class="nav-item dropdown"> |
| <a class="nav-link dropdown-toggle" href="#" id="ddFoundation" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> |
| ASF |
| </a> |
| <div class="dropdown-menu" aria-labelledby="ddFoundation"> |
| <a class="dropdown-item" href="https://www.apache.org/">ASF Home</a> |
| <a class="dropdown-item" href="https://www.apache.org/foundation/how-it-works.html">How it works</a> |
| <a class="dropdown-item" href="https://www.apache.org/licenses/">License</a> |
| <a class="dropdown-item" href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a> |
| <a class="dropdown-item" href="https://www.apache.org/foundation/thanks.html">Thanks</a> |
| <a class="dropdown-item" href="https://www.apache.org/security/">Security</a> |
| <a class="dropdown-item" href="https://www.apache.org/foundation/policies/conduct">Code of Conduct</a> |
| </div> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </nav> |
| |
| |
| <div class="section"> |
| <div class="container"> |
| <div class="row py-4"> |
| <div class="col-sm-12 card"> |
| <div class="card-body pt-5"> |
| |
| <a class="edit-on-gh" href="https://github.com/apache/celix-site/edit/master/source/docs/2.4.0/celix/documents/scheduled_events.md" title="Edit this page on GitHub">Edit on GitHub</a> |
| |
| |
| |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You 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. |
| --> |
| <h1 id="apache-celix-scheduled-events">Apache Celix Scheduled Events</h1> |
| <p>Apache Celix provides supports to schedule events on the Apache Celix Event Thread. This allows users to |
| reuse the existing Apache Celix events thread to do tasks on the event thread.</p> |
| <p>Scheduled events will be called repeatedly using a provided interval or once if |
| only an initial delay is provided. For the interval time, a monotonic clock is used.</p> |
| <p>The event callback should be relatively fast, and the scheduled event interval should be relatively high; otherwise, |
| the framework event queue will be blocked, and the framework will not function properly. |
| Network IO should not be done in the event callback, but instead, a separate thread should be used for this.</p> |
| <h2 id="scheduling-an-event">Scheduling an Event</h2> |
| <p>To schedule an event in the Apache Celix framework, use the <code>celix_bundleContext_scheduleEvent</code> C function or |
| <code>celix::BundleContext::scheduleEvent</code> C++ method. For C, an options struct is used to configure the scheduled event, |
| and for C++, a builder pattern is used to configure the scheduled event.</p> |
| <h3 id="c-example">C Example</h3> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-c" data-lang="c"><span style="display:flex;"><span><span style="color:#080">#include</span> <span style="color:#080"><stdio.h></span><span style="color:#080"> |
| </span></span></span><span style="display:flex;"><span><span style="color:#080">#include</span> <span style="color:#080"><celix_bundle_activator.h></span><span style="color:#080"> |
| </span></span></span><span style="display:flex;"><span><span style="color:#080"></span> |
| </span></span><span style="display:flex;"><span><span style="color:#a2f;font-weight:bold">typedef</span> <span style="color:#a2f;font-weight:bold">struct</span> schedule_events_bundle_activator_data { |
| </span></span><span style="display:flex;"><span> <span style="color:#0b0;font-weight:bold">celix_bundle_context_t</span><span style="color:#666">*</span> ctx; |
| </span></span><span style="display:flex;"><span> <span style="color:#0b0;font-weight:bold">long</span> scheduledEventId; |
| </span></span><span style="display:flex;"><span>} <span style="color:#0b0;font-weight:bold">schedule_events_bundle_activator_data_t</span>; |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">scheduleEventsBundle_oneShot</span>(<span style="color:#0b0;font-weight:bold">void</span><span style="color:#666">*</span> data) { |
| </span></span><span style="display:flex;"><span> <span style="color:#0b0;font-weight:bold">schedule_events_bundle_activator_data_t</span><span style="color:#666">*</span> act <span style="color:#666">=</span> data; |
| </span></span><span style="display:flex;"><span> <span style="color:#00a000">celix_bundleContext_log</span>(act<span style="color:#666">-></span>ctx, CELIX_LOG_LEVEL_INFO, <span style="color:#b44">"One shot scheduled event fired"</span>); |
| </span></span><span style="display:flex;"><span>} |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#0b0;font-weight:bold">void</span> <span style="color:#00a000">scheduleEventsBundle_process</span>(<span style="color:#0b0;font-weight:bold">void</span><span style="color:#666">*</span> data) { |
| </span></span><span style="display:flex;"><span> <span style="color:#0b0;font-weight:bold">schedule_events_bundle_activator_data_t</span><span style="color:#666">*</span> act <span style="color:#666">=</span> data; |
| </span></span><span style="display:flex;"><span> <span style="color:#00a000">celix_bundleContext_log</span>(act<span style="color:#666">-></span>ctx, CELIX_LOG_LEVEL_INFO, <span style="color:#b44">"Recurring scheduled event fired"</span>); |
| </span></span><span style="display:flex;"><span>} |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#a2f;font-weight:bold">static</span> <span style="color:#0b0;font-weight:bold">celix_status_t</span> <span style="color:#00a000">scheduleEventsBundle_start</span>(<span style="color:#0b0;font-weight:bold">schedule_events_bundle_activator_data_t</span> <span style="color:#666">*</span>data, <span style="color:#0b0;font-weight:bold">celix_bundle_context_t</span> <span style="color:#666">*</span>ctx) { |
| </span></span><span style="display:flex;"><span> data<span style="color:#666">-></span>ctx <span style="color:#666">=</span> ctx; |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#080;font-style:italic">//schedule recurring event |
| </span></span></span><span style="display:flex;"><span><span style="color:#080;font-style:italic"></span> { |
| </span></span><span style="display:flex;"><span> <span style="color:#0b0;font-weight:bold">celix_scheduled_event_options_t</span> opts <span style="color:#666">=</span> CELIX_EMPTY_SCHEDULED_EVENT_OPTIONS; |
| </span></span><span style="display:flex;"><span> opts.name <span style="color:#666">=</span> <span style="color:#b44">"recurring scheduled event example"</span>; |
| </span></span><span style="display:flex;"><span> opts.initialDelayInSeconds <span style="color:#666">=</span> <span style="color:#666">0.1</span>; |
| </span></span><span style="display:flex;"><span> opts.intervalInSeconds <span style="color:#666">=</span> <span style="color:#666">1.0</span>; |
| </span></span><span style="display:flex;"><span> opts.callbackData <span style="color:#666">=</span> data; |
| </span></span><span style="display:flex;"><span> opts.callback <span style="color:#666">=</span> scheduleEventsBundle_process; |
| </span></span><span style="display:flex;"><span> data<span style="color:#666">-></span>scheduledEventId <span style="color:#666">=</span> <span style="color:#00a000">celix_bundleContext_scheduleEvent</span>(ctx, <span style="color:#666">&</span>opts); |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#080;font-style:italic">//schedule one time event |
| </span></span></span><span style="display:flex;"><span><span style="color:#080;font-style:italic"></span> { |
| </span></span><span style="display:flex;"><span> <span style="color:#0b0;font-weight:bold">celix_scheduled_event_options_t</span> opts <span style="color:#666">=</span> CELIX_EMPTY_SCHEDULED_EVENT_OPTIONS; |
| </span></span><span style="display:flex;"><span> opts.name <span style="color:#666">=</span> <span style="color:#b44">"one shot scheduled event example"</span>; |
| </span></span><span style="display:flex;"><span> opts.initialDelayInSeconds <span style="color:#666">=</span> <span style="color:#666">0.1</span>; |
| </span></span><span style="display:flex;"><span> opts.callbackData <span style="color:#666">=</span> data; |
| </span></span><span style="display:flex;"><span> opts.callback <span style="color:#666">=</span> scheduleEventsBundle_oneShot; |
| </span></span><span style="display:flex;"><span> <span style="color:#00a000">celix_bundleContext_scheduleEvent</span>(ctx, <span style="color:#666">&</span>opts); |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#a2f;font-weight:bold">return</span> CELIX_SUCCESS; |
| </span></span><span style="display:flex;"><span>} |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#a2f;font-weight:bold">static</span> <span style="color:#0b0;font-weight:bold">celix_status_t</span> <span style="color:#00a000">scheduleEventsBundle_stop</span>(<span style="color:#0b0;font-weight:bold">schedule_events_bundle_activator_data_t</span> <span style="color:#666">*</span>data, <span style="color:#0b0;font-weight:bold">celix_bundle_context_t</span> <span style="color:#666">*</span>ctx) { |
| </span></span><span style="display:flex;"><span> <span style="color:#00a000">celix_bundleContext_removeScheduledEvent</span>(ctx, data<span style="color:#666">-></span>scheduledEventId); |
| </span></span><span style="display:flex;"><span> <span style="color:#a2f;font-weight:bold">return</span> CELIX_SUCCESS; |
| </span></span><span style="display:flex;"><span>} |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span><span style="color:#00a000">CELIX_GEN_BUNDLE_ACTIVATOR</span>(<span style="color:#0b0;font-weight:bold">schedule_events_bundle_activator_data_t</span>, scheduleEventsBundle_start, scheduleEventsBundle_stop) |
| </span></span></code></pre></div><h3 id="c-example-1">C++ Example</h3> |
| <div class="highlight"><pre tabindex="0" style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-cpp" data-lang="cpp"><span style="display:flex;"><span><span style="color:#080">#include</span> <span style="color:#080"><iostream></span><span style="color:#080"> |
| </span></span></span><span style="display:flex;"><span><span style="color:#080">#include</span> <span style="color:#080">"celix/BundleActivator.h"</span><span style="color:#080"> |
| </span></span></span><span style="display:flex;"><span><span style="color:#080"></span> |
| </span></span><span style="display:flex;"><span><span style="color:#a2f;font-weight:bold">class</span> <span style="color:#00f">ScheduleEventsBundleActivator</span> { |
| </span></span><span style="display:flex;"><span><span style="color:#a2f;font-weight:bold">public</span><span style="color:#666">:</span> |
| </span></span><span style="display:flex;"><span> <span style="color:#a2f;font-weight:bold">explicit</span> ScheduleEventsBundleActivator(<span style="color:#a2f;font-weight:bold">const</span> std<span style="color:#666">::</span>shared_ptr<span style="color:#666"><</span>celix<span style="color:#666">::</span>BundleContext<span style="color:#666">>&</span> ctx) { |
| </span></span><span style="display:flex;"><span> <span style="color:#080;font-style:italic">//schedule recurring event |
| </span></span></span><span style="display:flex;"><span><span style="color:#080;font-style:italic"></span> event <span style="color:#666">=</span> ctx<span style="color:#666">-></span>scheduledEvent() |
| </span></span><span style="display:flex;"><span> .withInitialDelay(std<span style="color:#666">::</span>chrono<span style="color:#666">::</span>milliseconds{<span style="color:#666">10</span>}) |
| </span></span><span style="display:flex;"><span> .withInterval(std<span style="color:#666">::</span>chrono<span style="color:#666">::</span>seconds{<span style="color:#666">1</span>}) |
| </span></span><span style="display:flex;"><span> .withCallback([ctx] { |
| </span></span><span style="display:flex;"><span> ctx<span style="color:#666">-></span>logInfo(<span style="color:#b44">"Recurring scheduled event fired"</span>); |
| </span></span><span style="display:flex;"><span> }) |
| </span></span><span style="display:flex;"><span> .build(); |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#080;font-style:italic">//schedule one time event |
| </span></span></span><span style="display:flex;"><span><span style="color:#080;font-style:italic"></span> ctx<span style="color:#666">-></span>scheduledEvent() |
| </span></span><span style="display:flex;"><span> .withInitialDelay(std<span style="color:#666">::</span>chrono<span style="color:#666">::</span>milliseconds{<span style="color:#666">10</span>}) |
| </span></span><span style="display:flex;"><span> .withCallback([ctx] { |
| </span></span><span style="display:flex;"><span> ctx<span style="color:#666">-></span>logInfo(<span style="color:#b44">"One shot scheduled event fired"</span>); |
| </span></span><span style="display:flex;"><span> }) |
| </span></span><span style="display:flex;"><span> .build(); |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span> <span style="color:#666">~</span>ScheduleEventsBundleActivator() <span style="color:#a2f;font-weight:bold">noexcept</span> { |
| </span></span><span style="display:flex;"><span> std<span style="color:#666">::</span>cout <span style="color:#666"><<</span> <span style="color:#b44">"Goodbye world"</span> <span style="color:#666"><<</span> std<span style="color:#666">::</span>endl; |
| </span></span><span style="display:flex;"><span> } |
| </span></span><span style="display:flex;"><span><span style="color:#a2f;font-weight:bold">private</span><span style="color:#666">:</span> |
| </span></span><span style="display:flex;"><span> celix<span style="color:#666">::</span>ScheduledEvent event{}; |
| </span></span><span style="display:flex;"><span>}; |
| </span></span><span style="display:flex;"><span> |
| </span></span><span style="display:flex;"><span>CELIX_GEN_CXX_BUNDLE_ACTIVATOR(ScheduleEventsBundleActivator) |
| </span></span></code></pre></div><h2 id="waking-up-a-scheduled-event">Waking up a Scheduled Event</h2> |
| <p>To process a scheduled event directly, you can use the <code>celix_bundleContext_wakeupScheduledEvent</code> C function or |
| <code>celix::ScheduledEvent::wakup</code> C++ method. This will wake up the scheduled event and call its callback function.</p> |
| |
| |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| |
| |
| <footer class="py-3 bg-secondary"> |
| <div class="container"> |
| <div class="row"> |
| <div class="col-md-8 text-center"> |
| <p class="m-0 text-white"> |
| Copyright © 2024 The Apache Software Foundation, Licensed under |
| the <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>. |
| <br> |
| Apache Celix, Celix, Apache, the Apache feather logo and the Apache Celix logo are trademarks of The Apache Software Foundation. |
| </p> |
| </div> |
| <div class="col-md-4 text-center"> |
| <a href="https://www.apache.org/events/current-event.html" target="_blank"> |
| <img src="https://www.apache.org/events/current-event-234x60.png" title="Apache Event" width="234" height="60" border="0"> |
| </a> |
| </div> |
| </div> |
| </div> |
| </footer> |
| |
| |
| <script src="/assets/js/jquery.min.js"></script> |
| <script src="/assets/js/bootstrap.bundle.min.js"></script> |
| |
| |
| </body> |
| </html> |
