blob: 698be028ce029aea2824e25c170df7c2616e3893 [file] [log] [blame]
/*
*
* Copyright (c) 2020 Project CHIP Authors
* Copyright (c) 2016-2017 Nest Labs, Inc.
*
* 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.
*/
/**
* This file defines the chip::System::Timer class and related types that can be used for representing
* an in-progress one-shot timer. Implementations of System::Layer may (but are not required to) use
* these for their versions of timer events.
*/
#pragma once
// Include configuration headers
#include <system/SystemConfig.h>
// Include dependent headers
#include <lib/support/DLLUtil.h>
#include <lib/support/Pool.h>
#include <system/SystemClock.h>
#include <system/SystemError.h>
#include <system/SystemLayer.h>
#include <system/SystemStats.h>
#if CHIP_SYSTEM_CONFIG_USE_DISPATCH
#include <dispatch/dispatch.h>
#endif
namespace chip {
namespace System {
class Layer;
/**
* Basic Timer information: time and callback.
*/
class DLL_EXPORT TimerData
{
public:
class Callback
{
public:
Callback(Layer & systemLayer, TimerCompleteCallback onComplete, void * appState) :
mSystemLayer(&systemLayer), mOnComplete(onComplete), mAppState(appState)
{}
void Invoke() const { mOnComplete(mSystemLayer, mAppState); }
const TimerCompleteCallback & GetOnComplete() const { return mOnComplete; }
void * GetAppState() const { return mAppState; }
Layer * GetSystemLayer() const { return mSystemLayer; }
private:
#if CHIP_SYSTEM_CONFIG_USE_LIBEV
friend class LayerImplSelect;
#endif
Layer * mSystemLayer;
TimerCompleteCallback mOnComplete;
void * mAppState;
};
TimerData(Layer & systemLayer, System::Clock::Timestamp awakenTime, TimerCompleteCallback onComplete, void * appState) :
mAwakenTime(awakenTime), mCallback(systemLayer, onComplete, appState)
{}
~TimerData() = default;
/**
* Return the expiration time.
*/
Clock::Timestamp AwakenTime() const { return mAwakenTime; }
/**
* Return callback information.
*/
const Callback & GetCallback() const { return mCallback; }
private:
Clock::Timestamp mAwakenTime;
Callback mCallback;
#if CHIP_SYSTEM_CONFIG_USE_DISPATCH
friend class LayerImplSelect;
dispatch_source_t mTimerSource = nullptr;
#elif CHIP_SYSTEM_CONFIG_USE_LIBEV
friend class LayerImplSelect;
struct ev_timer mLibEvTimer;
#endif // CHIP_SYSTEM_CONFIG_USE_DISPATCH
// Not defined
TimerData(const TimerData &) = delete;
TimerData & operator=(const TimerData &) = delete;
};
/**
* List of `Timer`s ordered by expiration time.
*/
class TimerList
{
public:
class Node : public TimerData
{
public:
Node(Layer & systemLayer, System::Clock::Timestamp awakenTime, TimerCompleteCallback onComplete, void * appState) :
TimerData(systemLayer, awakenTime, onComplete, appState), mNextTimer(nullptr)
{}
Node * mNextTimer;
};
TimerList() : mEarliestTimer(nullptr) {}
/**
* Add a timer to the list
*
* @return The new earliest timer in the list. If this is the newly added timer, that implies it is earlier
* than any existing timer.
*/
Node * Add(Node * timer);
/**
* Remove the given timer from the list, if present. It is not an error for the timer not to be present.
*
* @return The new earliest timer in the list, or nullptr if the list is empty.
*/
Node * Remove(Node * remove);
/**
* Remove the first timer with the given properties, if present. It is not an error for no such timer to be present.
*
* @return The removed timer, or nullptr if the list contains no matching timer.
*/
Node * Remove(TimerCompleteCallback onComplete, void * appState);
/**
* Remove and return the earliest timer in the list.
*
* @return The earliest timer, or nullptr if the list is empty.
*/
Node * PopEarliest();
/**
* Remove and return the earliest timer in the list, provided it expires earlier than the given time @a t.
*
* @return The earliest timer expiring before @a t, or nullptr if there is no such timer.
*/
Node * PopIfEarlier(Clock::Timestamp t);
/**
* Get the earliest timer in the list.
*
* @return The earliest timer, or nullptr if there are no timers.
*/
Node * Earliest() const { return mEarliestTimer; }
/**
* Test whether there are any timers.
*/
bool Empty() const { return mEarliestTimer == nullptr; }
/**
* Remove and return all timers that expire before the given time @a t.
*/
TimerList ExtractEarlier(Clock::Timestamp t);
/**
* Remove all timers.
*/
void Clear() { mEarliestTimer = nullptr; }
/**
* Find the timer with the given properties, if present, and return its remaining time
*
* @return The remaining time on this partifcular timer or 0 if not found.
*/
Clock::Timeout GetRemainingTime(TimerCompleteCallback aOnComplete, void * aAppState);
private:
Node * mEarliestTimer;
};
/**
* ObjectPool wrapper that keeps System Timer statistics.
*/
template <typename T = TimerList::Node>
class TimerPool
{
public:
using Timer = T;
/**
* Create a new timer from the pool.
*/
Timer * Create(Layer & systemLayer, System::Clock::Timestamp awakenTime, TimerCompleteCallback onComplete, void * appState)
{
Timer * timer = mTimerPool.CreateObject(systemLayer, awakenTime, onComplete, appState);
SYSTEM_STATS_INCREMENT(Stats::kSystemLayer_NumTimers);
return timer;
}
/**
* Release a timer to the pool.
*/
void Release(Timer * timer)
{
SYSTEM_STATS_DECREMENT(Stats::kSystemLayer_NumTimers);
mTimerPool.ReleaseObject(timer);
}
/**
* Release all timers.
*/
void ReleaseAll()
{
SYSTEM_STATS_RESET(Stats::kSystemLayer_NumTimers);
mTimerPool.ReleaseAll();
}
/**
* Release a timer to the pool and invoke its callback.
*/
void Invoke(Timer * timer)
{
typename Timer::Callback callback = timer->GetCallback();
Release(timer);
callback.Invoke();
}
private:
friend class TestSystemTimer_CheckTimerPool_Test;
ObjectPool<Timer, CHIP_SYSTEM_CONFIG_NUM_TIMERS> mTimerPool;
};
} // namespace System
} // namespace chip