TaskBase.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_BASE_H
00019 #define TASK_BASE_H
00020 
00021 #include "platform/Callback.h"
00022 #include "platform/mbed_assert.h"
00023 #include "LinkEntry.h"
00024 
00025 namespace rtos {
00026 class Semaphore;
00027 }
00028 
00029 namespace events {
00030 
00031 class TaskQueue;
00032 
00033 /**
00034  * \defgroup drivers_TaskBase TaskBase class
00035  * \ingroup drivers-internal-api-usb
00036  * @{
00037  */
00038 
00039 /** TaskBase
00040  *
00041  *  Representation of a caller allocated task
00042  */
00043 class TaskBase : public LinkEntry {
00044 public:
00045 
00046     typedef void (*run_callback_t)(void *data);
00047 
00048     /**
00049      * Construct a new TaskBase object
00050      *
00051      * @param q Queue for posting to
00052      */
00053     TaskBase(TaskQueue *q);
00054 
00055     /**
00056      * Destroy this TaskBase
00057      */
00058     virtual ~TaskBase();
00059 
00060     /**
00061      * Set the queue of this task
00062      *
00063      * @param q TaskQueue to post to
00064      */
00065     void set(TaskQueue *q);
00066 
00067     /**
00068      * Cancel the execution of this task
00069      *
00070      * Once cancelled the task can be posted again. Previous
00071      * calls to post may still run. If you need to ensure the
00072      * callback has finished the function wait() can be used.
00073      *
00074      * @note This function is interrupt safe
00075      */
00076     void cancel();
00077 
00078     /**
00079      * Return true if this task is ready to be posted
00080      *
00081      * Check if this task is on a queue waiting to be run.
00082      *
00083      * @return true if it is safe to call post
00084      */
00085     bool ready();
00086 
00087     /**
00088      * Wait for this task to finish execution
00089      *
00090      * When this function returns then this task is in the finished state.
00091      */
00092     void wait();
00093 
00094     /**
00095      * Check if the callback has run to completion or been fully canceled
00096      *
00097      * When an task is finished the queue is completely done with it and the
00098      * callback is either fully complete or has been canceled and will not run.
00099      *
00100      * @return true if this task has been flushed from the queue, false otherwise
00101      */
00102     bool finished();
00103 
00104 protected:
00105 
00106     /**
00107      * Size of buffer required for TaskBase::start
00108      *
00109      * @return requested buffer size
00110      */
00111     virtual uint32_t size() = 0;
00112 
00113     /**
00114      * Copy any callback data and return a callback to run
00115      *
00116      * @param data Buffer to copy data to. Do not copy more than TaskBase::size() data.
00117      * @param size Maximum size to copy
00118      */
00119     virtual run_callback_t start(void *data, uint32_t size) = 0;
00120 
00121     /**
00122      * Inform this task that execution has finished.
00123      *
00124      */
00125     virtual void finish();
00126 
00127     /**
00128      * Post this task to the set TaskQueue for execution
00129      */
00130     void post();
00131 
00132 private:
00133 
00134     TaskQueue *_queue;
00135     bool _posted;
00136     uint16_t _start_count;
00137     rtos::Semaphore *_flush_sem;
00138 
00139     friend class TaskQueue;
00140 
00141     /*
00142      * Must be called in a critical section
00143      *
00144      * This function should not be called directly. Instead
00145      * TaskQueue::task_start should be used instead.
00146      */
00147     run_callback_t _start(void *buffer, uint32_t size);
00148 
00149     /*
00150      * Must be called in a critical section
00151      *
00152      * This function should not be called directly. Instead
00153      * TaskQueue::task_finish should be used instead.
00154      *
00155      */
00156     void _finish();
00157 
00158     /*
00159      * Unblock wait if this task is finished
00160      */
00161     void _wake_check();
00162 };
00163 
00164 /** @}*/
00165 
00166 }
00167 
00168 #endif