Mbed OS Reference | UserAllocatedEvent.h Source File

 /*
  * Copyright (c) 2019 ARM Limited
  * SPDX-License-Identifier: Apache-2.0
  *
  * 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.
  */
 #ifndef USER_ALLOCATED_EVENT_H
 #define USER_ALLOCATED_EVENT_H
 
 #include "events/EventQueue.h"
 #include "platform/mbed_assert.h"
 #include "platform/mbed_atomic.h"
 
 namespace events {
 /**
  * \addtogroup events-public-api
  * @{
  */
 template <typename F, typename A>
 class UserAllocatedEvent;
 
 /**
  * \defgroup events_Event UserAllocatedEvent class
  * @{
  */
 
 /** UserAllocatedEvent
  *
  *  Representation of an static event for fine-grain dispatch control.
  *
  *  UserAllocatedEvent provides mechanism for event posting and dispatching
  *  without utilization of queue internal memory. It embeds all underlying
  *  event data and doesn't require any memory allocation while posting and dispatching.
  *  All of these makes it cannot fail due to memory exhaustion while posting
  *
  * Usage:
  * @code
  *  #include "mbed.h"
  *
  *  void handler(int data) { ... }
  *
  *  class Device {
  *     public:
  *     void handler(int data) { ... }
  *  };
  *
  *  Device dev;
  *
  *  // queue with not internal storage for dynamic events
  *  // accepts only user allocated events
  *  static EventQueue queue(0);
  *  // Create events
  *  static auto e1 = make_user_allocated_event(&dev, Device::handler, 2);
  *  static auto e2 = queue.make_user_allocated_event(handler, 3);
  *
  *  int main()
  *  {
  *    e1.call_on(&queue);
  *    e2.call();
  *
  *    queue.dispatch(1);
  *  }
  * @endcode
  */
 template <typename F, typename... ArgTs>
 class UserAllocatedEvent<F, void(ArgTs...)> {
 public:
     typedef EventQueue::context<F, ArgTs...> C;
 
     /** Create an event
      *
      *  Constructs an event. The specified callback acts as the target
      *  for the event and is executed in the context of the
      *  event queue's dispatch loop once posted.
      *
      *  @param f        Function to execute when the event is dispatched
      *  @param args     Arguments to bind to the callback
      */
     constexpr UserAllocatedEvent(F f,  ArgTs... args) : _e(get_default_equeue_event()), _c(f, args...), _equeue(), _post_ref()
     {
     }
 
     /** Create an event
      *
      *  Constructs an event. The specified callback acts as the target
      *  for the event and is executed in the context of the
      *  event queue's dispatch loop once posted.
      *
      *  @param queue    Event queue to dispatch on
      *  @param f        Function to execute when the event is dispatched
      *  @param args     Arguments to bind to the callback
      */
     constexpr UserAllocatedEvent(EventQueue *queue, F f,  ArgTs... args) : _e(get_default_equeue_event()), _c(f, args...), _equeue(&queue->_equeue), _post_ref()
     {
     }
 
     /** Destructor for events
      */
 #if !defined(NDEBUG)
     // Remove the user provided destructor in release to allow constexpr optimization
     // constexpr requires destructor to be trivial and only default one is treated as trivial
     ~UserAllocatedEvent()
     {
         MBED_ASSERT(!_post_ref);
     }
 #endif
 
     /** Posts an event onto the underlying event queue, returning void
     *
     *  The event is posted to the underlying queue and is executed in the
     *  context of the event queue's dispatch loop.
     *
     *  This call cannot fail due queue memory exhaustion
     *  because it doesn't allocate any memory
     *
     *  The post function is IRQ safe and can act as a mechanism for moving
     *  events out of IRQ contexts.
     *
     */
     void call()
     {
         MBED_ASSERT(!_post_ref);
         MBED_ASSERT(_equeue);
         MBED_UNUSED bool status = post();
         MBED_ASSERT(status);
     }
 
     /** Posts an event onto the event queue passed as argument, returning void
     *
     *  The event is posted to the event queue passed as argument
     *  and is executed in the context of the event queue's dispatch loop.
     *
     *  This call cannot fail due queue memory exhaustion
     *  because it doesn't allocate any memory
     *
     *  The post function is IRQ safe and can act as a mechanism for moving
     *  events out of IRQ contexts.
     *
     *  @param queue    Event queue to dispatch on. Will replace earlier bound EventQueue.
     *
     */
     void call_on(EventQueue *queue)
     {
         MBED_ASSERT(!_post_ref);
         MBED_UNUSED bool status = post_on(queue);
         MBED_ASSERT(status);
     }
 
     /** Posts an event onto the underlying event queue
     *
     *  The event is posted to the event queue passed as argument
     *  and is executed in the context of the event queue's dispatch loop.
     *
     *  This call cannot fail due queue memory exhaustion
     *  because it doesn't allocate any memory
     *
     *  @return     False if the event was already posted
     *              true otherwise
     *
     */
     bool try_call()
     {
         return post();
     }
 
     /** Posts an event onto the event queue passed as argument,
     *
     *  The event is posted to the underlying queue and is executed in the
     *  context of the event queue's dispatch loop.
     *
     *  This call cannot fail due queue memory exhaustion
     *  because it doesn't allocate any memory
     *
     *  @param queue    Event queue to dispatch on. Will replace earlier bound EventQueue.
     *  @return         False if the event was already posted
     *                  true otherwise
     *
     */
     bool try_call_on(EventQueue *queue)
     {
         return post_on(queue);
     }
 
     /** Posts an event onto the underlying event queue, returning void
      *
      *  The event is posted to the underlying queue and is executed in the
      *  context of the event queue's dispatch loop.
      *
      *  This call cannot fail due queue memory exhaustion
      *  because it doesn't allocate any memory
      *
      *  The post function is IRQ safe and can act as a mechanism for moving
      *  events out of IRQ contexts.
      *
      */
     void operator()()
     {
         return call();
     }
 
     /** Configure the delay of an event
      *
      *  @param delay    Millisecond delay before dispatching the event
      */
     void delay(int delay)
     {
         MBED_ASSERT(!_post_ref);
         equeue_event_delay(&_e + 1, delay);
     }
 
     /** Configure the period of an event
      *
      *  @param period   Millisecond period for repeatedly dispatching an event
      */
     void period(int period)
     {
         MBED_ASSERT(!_post_ref);
         equeue_event_period(&_e + 1, period);
     }
 
     /** Cancels posted event
      *
      *  Attempts to cancel posted event. It is safe to call
      *  cancel after an event has already been dispatched.
      *
      *  The cancel function is IRQ safe.
      *
      *  If called while the event queue's dispatch loop is active, the cancel
      *  function does not guarantee that the event will not execute after it
      *  returns, as the event may have already begun executing.
      *
      *  @return     true if event was successfully cancelled
      */
     bool cancel()
     {
         return equeue_cancel_user_allocated(_equeue, &_e);
     }
 
 
 private:
     friend class EventQueue;
     struct equeue_event _e;
     C _c;
     struct equeue *_equeue;
     uint8_t _post_ref;
 
     bool post()
     {
         if (_post_ref) {
             return false;
         }
         core_util_atomic_incr_u8(&_post_ref, 1);
         equeue_post_user_allocated(_equeue, &EventQueue::function_call<C>, &_e);
         return true;
     }
 
     bool post_on(EventQueue *queue)
     {
         if (_post_ref) {
             return false;
         }
         _equeue = &(queue->_equeue);
         core_util_atomic_incr_u8(&_post_ref, 1);
         equeue_post_user_allocated(_equeue, &EventQueue::function_call<C>, &_e);
         return true;
     }
 
     static void event_dtor(void *p)
     {
         UserAllocatedEvent<F, void(ArgTs...)> *instance = (UserAllocatedEvent<F, void(ArgTs...)> *)(((equeue_event *)p) - 1);
         core_util_atomic_decr_u8(&instance->_post_ref, 1);
         MBED_ASSERT(!instance->_post_ref);
     }
 
     constexpr static equeue_event get_default_equeue_event()
     {
         return equeue_event{ 0, 0, 0, NULL, NULL, NULL, 0, -1, &UserAllocatedEvent::event_dtor, NULL };
     }
 
 public:
 
     /** Create an event
      *  @see UserAllocatedEvent::UserAllocatedEvent
      */
     template <typename T, typename R>
     constexpr UserAllocatedEvent(T *obj, R(T::*method)(ArgTs...), ArgTs... args) :
         UserAllocatedEvent(mbed::callback(obj, method), args...) { }
 
     /** Create an event
      *  @see UserAllocatedEvent::UserAllocatedEvent
      */
     template <typename T, typename R>
     constexpr UserAllocatedEvent(EventQueue *q, T *obj, R(T::*method)(ArgTs...), ArgTs... args) :
         UserAllocatedEvent(q, mbed::callback(obj, method), args...) { }
 
     /** Create an event
      *  @see UserAllocatedEvent::UserAllocatedEvent
      */
     template <typename T, typename R>
     constexpr UserAllocatedEvent(const T *obj, R(T::*method)(ArgTs...) const, ArgTs... args) :
         UserAllocatedEvent(mbed::callback(obj, method), args...) { }
 
     /** Create an event
      *  @see UserAllocatedEvent::UserAllocatedEvent
      */
     template <typename T, typename R>
     constexpr UserAllocatedEvent(EventQueue *q, const T *obj, R(T::*method)(ArgTs...) const, ArgTs... args) :
         UserAllocatedEvent(q, mbed::callback(obj, method), args...) { }
 
     /** Create an event
      *  @see UserAllocatedEvent::UserAllocatedEvent
      */
     template <typename T, typename R>
     constexpr UserAllocatedEvent(volatile T *obj, R(T::*method)(ArgTs...) volatile, ArgTs... args) :
         UserAllocatedEvent(mbed::callback(obj, method), args...) { }
 
     /** Create an event
      *  @see UserAllocatedEvent::UserAllocatedEvent
      */
     template <typename T, typename R>
     constexpr UserAllocatedEvent(EventQueue *q, volatile T *obj, R(T::*method)(ArgTs...) volatile, ArgTs... args) :
         UserAllocatedEvent(q, mbed::callback(obj, method), args...) { }
 
     /** Create an event
      *  @see UserAllocatedEvent::UserAllocatedEvent
      */
     template <typename T, typename R>
     constexpr UserAllocatedEvent(const volatile T *obj, R(T::*method)(ArgTs...) const volatile, ArgTs... args) :
         UserAllocatedEvent(mbed::callback(obj, method), args...) { }
 
     /** Create an event
      *  @see UserAllocatedEvent::UserAllocatedEvent
      */
     template <typename T, typename R>
     constexpr UserAllocatedEvent(EventQueue *q, const volatile T *obj, R(T::*method)(ArgTs...) const volatile, ArgTs... args) :
         UserAllocatedEvent(q, mbed::callback(obj, method), args...) { }
 };
 
 // Convenience functions declared here to avoid cyclic
 // dependency between Event and EventQueue
 template <typename F, typename... ArgTs>
 UserAllocatedEvent<F, void(ArgTs...)> EventQueue::make_user_allocated_event(F f, ArgTs... args)
 {
     return UserAllocatedEvent<F, void(ArgTs...)>(this, f, args...);
 }
 
 template <typename T, typename R, typename... ArgTs>
 UserAllocatedEvent<mbed::Callback<void(ArgTs...)>, void(ArgTs...)> EventQueue::make_user_allocated_event(T *obj, R(T::*method)(ArgTs... args), ArgTs... args)
 {
     return UserAllocatedEvent<mbed::Callback<void(ArgTs...)>, void(ArgTs...)>(this, mbed::callback(obj, method), args...);
 }
 
 template <typename T, typename R, typename... ArgTs>
 UserAllocatedEvent<mbed::Callback<void(ArgTs...)>, void(ArgTs...)> EventQueue::make_user_allocated_event(const T *obj, R(T::*method)(ArgTs... args) const, ArgTs... args)
 {
     return UserAllocatedEvent<mbed::Callback<void(ArgTs...)>, void(ArgTs...)>(this, mbed::callback(obj, method), args...);
 }
 
 template <typename T, typename R, typename... ArgTs>
 UserAllocatedEvent<mbed::Callback<void(ArgTs...)>, void(ArgTs...)> EventQueue::make_user_allocated_event(volatile T *obj, R(T::*method)(ArgTs... args) volatile, ArgTs... args)
 {
     return UserAllocatedEvent<mbed::Callback<void(ArgTs...)>, void(ArgTs...)>(this, mbed::callback(obj, method), args...);
 }
 
 template <typename T, typename R, typename... ArgTs>
 UserAllocatedEvent<mbed::Callback<void(ArgTs...)>, void(ArgTs...)> EventQueue::make_user_allocated_event(const volatile T *obj, R(T::*method)(ArgTs... args) const volatile, ArgTs... args)
 {
     return UserAllocatedEvent<mbed::Callback<void(ArgTs...)>, void(ArgTs...)>(this, mbed::callback(obj, method), args...);
 }
 
 
 /** Creates a UserAllocatedEvent object, deducing the target type from the types of arguments
  *
  *  UserAllocatedEvent doesn't utilize EventQueue internal memory,
  *  therefore it can be posted on the queue without being afraid
  *  of post fail due to queue memory exhaustion
  *
  *  @return  UserAllocatedEvent object instance
  *
  */
 template <typename F, typename... ArgTs>
 constexpr UserAllocatedEvent<F, void(ArgTs...)> make_user_allocated_event(F f, ArgTs... args)
 {
     return UserAllocatedEvent<F, void(ArgTs...)>(f, args...);
 }
 
 /** Creates a UserAllocatedEvent object, deducing the target type from the types of arguments
  *
  *  UserAllocatedEvent doesn't utilize EventQueue internal memory,
  *  therefore it can be posted on the queue without being afraid
  *  of post fail due to queue memory exhaustion
  *
  *  @return  UserAllocatedEvent object instance
  *
  */
 template <typename T, typename R, typename... ArgTs>
 constexpr UserAllocatedEvent<mbed::Callback<void(ArgTs...)>, void(ArgTs...)> make_user_allocated_event(T *obj, R(T::*method)(ArgTs... args), ArgTs... args)
 {
     return UserAllocatedEvent<mbed::Callback<void(ArgTs...)>, void(ArgTs...)>(mbed::callback(obj, method), args...);
 }
 
 /** Creates a UserAllocatedEvent object, deducing the target type from the types of arguments
  *
  *  UserAllocatedEvent doesn't utilize EventQueue internal memory,
  *  therefore it can be posted on the queue without being afraid
  *  of post fail due to queue memory exhaustion
  *
  *  @return  UserAllocatedEvent object instance
  *
  */
 template <typename T, typename R, typename... ArgTs>
 constexpr UserAllocatedEvent<mbed::Callback<void(ArgTs...)>, void(ArgTs...)> make_user_allocated_event(const T *obj, R(T::*method)(ArgTs... args) const, ArgTs... args)
 {
     return UserAllocatedEvent<mbed::Callback<void(ArgTs...)>, void(ArgTs...)>(mbed::callback(obj, method), args...);
 }
 
 /** Creates a UserAllocatedEvent object, deducing the target type from the types of arguments
  *
  *  UserAllocatedEvent doesn't utilize EventQueue internal memory,
  *  therefore it can be posted on the queue without being afraid
  *  of post fail due to queue memory exhaustion
  *
  *  @return  UserAllocatedEvent object instance
  *
  */
 template <typename T, typename R, typename... ArgTs>
 constexpr UserAllocatedEvent<mbed::Callback<void(ArgTs...)>, void(ArgTs...)> make_user_allocated_event(volatile T *obj, R(T::*method)(ArgTs... args) volatile, ArgTs... args)
 {
     return UserAllocatedEvent<mbed::Callback<void(ArgTs...)>, void(ArgTs...)>(mbed::callback(obj, method), args...);
 }
 
 /** Creates a UserAllocatedEvent object, deducing the target type from the types of arguments
  *
  *  UserAllocatedEvent doesn't utilize EventQueue internal memory,
  *  therefore it can be posted on the queue without being afraid
  *  of post fail due to queue memory exhaustion
  *
  *  @return  UserAllocatedEvent object instance
  *
  */
 template <typename T, typename R, typename... ArgTs>
 constexpr UserAllocatedEvent<mbed::Callback<void(ArgTs...)>, void(ArgTs...)> make_user_allocated_event(const volatile T *obj, R(T::*method)(ArgTs... args) const volatile, ArgTs... args)
 {
     return UserAllocatedEvent<mbed::Callback<void(ArgTs...)>, void(ArgTs...)>(mbed::callback(obj, method), args...);
 }
 
 /** @}*/
 
 /** @}*/
 }
 #endif
Important Information for this Arm website
