event_loop.h revision e64f180233e64c40b56993cfea3696c5b4b16395 
1/*
2 * Copyright (C) 2016 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17#ifndef CHRE_CORE_EVENT_LOOP_H_
18#define CHRE_CORE_EVENT_LOOP_H_
19
20// TODO: using std lib for initial test... we can't do this in the real world
21#include <atomic>
22#include <vector>
23
24#include "chre/core/event.h"
25#include "chre/core/nanoapp.h"
26#include "chre/util/blocking_queue.h"
27#include "chre/util/non_copyable.h"
28#include "chre/util/vector.h"
29
30namespace chre {
31
32/**
33 * TODO: document this better
34 */
35class EventLoop : public NonCopyable {
36 public:
37  // TODO: need a clear delineation for which methods are safe to call from
38  // threads other than the one calling run()... should include stop() and
39  // postEvent()... everything else would decidedly be not thread-safe
40
41  /**
42   * Starts a nanoapp by invoking the start entry point. If this is successful,
43   * the app is managed by the event loop and the pointer passed in must remain
44   * valid.
45   *
46   * @param A pointer to the nanoapp to start.
47   * @return True if the app was started successfully.
48   */
49  bool startNanoapp(Nanoapp *nanoapp);
50
51  /**
52   * Stops a nanoapp by invoking the stop entry point. The nanoapp passed in
53   * must have been previously started by the startNanoapp method.
54   *
55   * @param A pointer to the nanoapp to stop.
56   */
57  void stopNanoapp(Nanoapp *nanoapp);
58
59  /**
60   * Start the main task run loop. Only returns after stop() is called
61   * (from another context).
62   */
63  void run();
64
65  /**
66   * Signals the event loop currently executing in run() to exit gracefully at
67   * the next available opportunity.
68   */
69  void stop();
70
71  // TODO: this is safe to call from other threads, and posts to the incoming
72  // event queue, then it is doled out to interested nanoapp queues later
73  void postEvent(Event *event);
74
75  // TODO: static method that allocates + constructs + posts an Event to all
76  // EventLoops (i.e. just the one for now), to simplify external code that will
77  // call this (they don't need to worry about how events are allocated, etc)
78
79  // TODO: do we need this? it might be a helpful convenience function that
80  // handles creation of a timer and stuff
81  void postEventDelayed(Event *event, uint64_t delayNs);
82
83  /**
84   * Returns a pointer to the currently executing Nanoapp, or nullptr if none is
85   * currently executing.
86   *
87   * @return a pointer to the currently executing nanoapp and nullptr if not
88   * currently in an app context.
89   */
90  const Nanoapp *getCurrentNanoapp() const;
91
92  /**
93   * Returns a guaranteed unique instance ID that can be used to construct a
94   * nanoapp.
95   *
96   * @return a unique instance ID to assign to a nanoapp.
97   */
98  uint32_t getNextInstanceId();
99
100 private:
101  //! The instance ID that was previously generated by getNextInstanceId.
102  uint32_t mLastInstanceId = kSystemInstanceId;
103
104  // TODO: replace STL use with our own data structures
105  std::vector<Nanoapp*> mNanoapps;
106  BlockingQueue<Event*> mEvents;
107
108  // TODO: we probably want our own atomic platform abstraction too
109  std::atomic<bool> mRunning{false};
110
111  Nanoapp *mCurrentApp = nullptr;
112
113  void freeEvent(Event *event);
114  Nanoapp *lookupAppByInstanceId(uint32_t instanceId);
115
116  // TODO: we probably want a to model kSystemInstanceId as an actual nanoapp
117  // with entry points and all that to make it simpler to post events to ourself
118  // and the like...
119};
120
121}  // namespace chre
122
123#endif  // CHRE_CORE_EVENT_LOOP_H_
124