TaskQueue.h

00001 /*
00002  * Copyright (c) 2018-2019, Arm Limited and affiliates.
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 
00018 #ifndef TASK_QUEUE_H
00019 #define TASK_QUEUE_H
00020 
00021 #include "drivers/internal/TaskBase.h"
00022 #include "platform/Callback.h"
00023 #include "mbed_critical.h"
00024 
00025 #define MBED_MAX_TASK_SIZE  32
00026 
00027 namespace events {
00028 
00029 /**
00030  * \defgroup drivers_TaskQueue TaskQueue class
00031  * \ingroup drivers-internal-api-usb
00032  * @{
00033  */
00034 
00035 /** TaskQueue
00036  *
00037  *  Flexible task queue for dispatching tasks
00038  */
00039 class TaskQueue {
00040 public:
00041 
00042     /** Create a TaskQueue
00043      *
00044      *  Create an event queue.
00045      */
00046     TaskQueue()
00047     {
00048 
00049     }
00050 
00051     /** Destroy a TaskQueue
00052      */
00053     virtual ~TaskQueue()
00054     {
00055 
00056     }
00057 
00058     /**
00059      * Add this event to the queue for execution
00060      *
00061      * If the event is already in the queue then it is canceled and
00062      * added to the end of the queue.
00063      *
00064      *  @param event    Pointer to the event
00065      */
00066     virtual void post(TaskBase *event) = 0;
00067 
00068     /** Cancel an in-flight event
00069      *
00070      *  Cancels the given event so the event's memory can be reused.
00071      *
00072      *  The cancel function is IRQ safe.
00073      *
00074      *  If called while the event queue's dispatch loop is active, the cancel
00075      *  function does not guarantee that the event will not execute after it
00076      *  returns, as the event may have already begun executing. It does
00077      *  guarantee that the event queue is no longer using event data so
00078      *  the event can be freed or reused.
00079      *
00080      *  @param event    Pointer to the event
00081      */
00082     virtual void cancel(TaskBase *event) = 0;
00083 
00084 protected:
00085 
00086     /**
00087      * Get the size required to run this task
00088      *
00089      * Get the minimum size required for TaskQueue::task_start
00090      *
00091      * @param task The task to check size on
00092      * @return required size
00093      * @note This call must be made in a critical section
00094      */
00095     static uint32_t task_size(TaskBase *task)
00096     {
00097 
00098         return task->size();
00099     }
00100 
00101     /**
00102      * Start processing this event by copying out its data
00103      *
00104      * Inform this event both that callback execution has started
00105      * and that the event is free to be posted again.
00106      *
00107      * @param task The task to start processing
00108      * @param dest The buffer to copy the callback arguments to
00109      * @param size maximum size to copy
00110      * @return Pointer to function run
00111      *
00112      * @note event_start must not be called on a canceled event as the
00113      *                   memory may have been freed already
00114      * @note Every call to event_start must be paired with event_finish
00115      * @note This call must be made in a critical section
00116      */
00117     static TaskBase::run_callback_t task_start(TaskBase *task, uint8_t *dest, uint32_t size)
00118     {
00119 
00120         return task->_start(dest, size);
00121     }
00122 
00123     /**
00124      * Finish processing this event
00125      *
00126      * Inform this event that the callback has run to completion.
00127      *
00128      * @param task The task to finish processing
00129      *
00130      * @note Every call to event_finish must be preceded by a call to event_start
00131      * @note This call must be made in a critical section
00132      */
00133     static void task_finish(TaskBase *task)
00134     {
00135         task->_finish();
00136     }
00137 };
00138 
00139 /** @}*/
00140 
00141 }
00142 #endif