Repository: raspberrypi/pico-sdk
File: src/common/pico_time/include/pico/time.h (C/C++)

Code before:
 * @return >0 the alarm id
 * @return 0 if the alarm timestamp happened before or during the call AND there is no active alarm to return the id of.
 *           The latter can either happen because fire_if_past was false (i.e. no timer was ever created),
 *           or if the callback <i>was</i> called during this method but the callback cancelled itself by returning 0
 * @return -1 if there were no alarm slots available
 */
static inline alarm_id_t alarm_pool_add_alarm_in_us(alarm_pool_t *pool, uint64_t us, alarm_callback_t callback, void *user_data, bool fire_if_past) {
    return alarm_pool_add_alarm_at(pool, delayed_by_us(get_absolute_time(), us), callback, user_data, fire_if_past);
}

/*!
 * \brief Add an alarm callback to be called after a delay specified in milliseconds
 * \ingroup alarm
 *
 * Generally the callback is called as soon as possible after the time specified from an IRQ handler
 * on the core the alarm pool was created on. If the callback is in the past or happens before
 * the alarm setup could be completed, then this method will optionally call the callback itself
 * and then return a return code to indicate that the target time has passed.
 *
 * \note It is safe to call this method from an IRQ handler (including alarm callbacks), and from either core.
 *
 * @param pool the alarm pool to use for scheduling the callback (this determines which hardware alarm is used, and which core calls the callback)
 * @param ms the delay (from now) in milliseconds when (after which) the callback should fire
 * @param callback the callback function
 * @param user_data user data to pass to the callback function
 * @param fire_if_past if true, and the timestamp falls before or during this call before the alarm can be set, 
 *                     then the callback should be called during (by) this function instead 
* @return >0 the alarm id
 * @return 0 if the alarm timestamp happened before or during the call AND there is no active alarm to return the id of.
 *           The latter can either happen because fire_if_past was false (i.e. no timer was ever created),
 *           or if the callback <i>was</i> called during this method but the callback cancelled itself by returning 0
 * @return -1 if there were no alarm slots available
 */
static inline alarm_id_t alarm_pool_add_alarm_in_ms(alarm_pool_t *pool, uint32_t ms, alarm_callback_t callback, void *user_data, bool fire_if_past) {
    return alarm_pool_add_alarm_at(pool, delayed_by_ms(get_absolute_time(), ms), callback, user_data, fire_if_past);
}

/*!
 * \brief Cancel an alarm
 * \ingroup alarm
 * \param pool the alarm_pool containing the alarm
 * \param alarm_id the alarm
 * \return true if the alarm was cancelled, false if it didn't exist
 * \sa alarm_id_t for a note on reuse of IDs
 */
bool alarm_pool_cancel_alarm(alarm_pool_t *pool, alarm_id_t alarm_id);

#if !PICO_TIME_DEFAULT_ALARM_POOL_DISABLED
/*!
 * \brief Add an alarm callback to be called at a specific time
 * \ingroup alarm

Review comment (suggestion):
I see that you've got two variations of this comment - one that uses "timestamp" and one that uses "timeout". Was this function (`alarm_pool_add_alarm_in_ms`) supposed to use the "timeout" variant? (I see that `add_alarm_in_ms` uses the "timeout" variant, so presumably at least one of them needs changing? :shrug: )

Code after:
 * @return >0 the alarm id
 * @return 0 if the alarm time passed before or during the call AND there is no active alarm to return the id of.
 *           The latter can either happen because fire_if_past was false (i.e. no timer was ever created),
 *           or if the callback <i>was</i> called during this method but the callback cancelled itself by returning 0
 * @return -1 if there were no alarm slots available
 */
static inline alarm_id_t alarm_pool_add_alarm_in_us(alarm_pool_t *pool, uint64_t us, alarm_callback_t callback, void *user_data, bool fire_if_past) {
    return alarm_pool_add_alarm_at(pool, delayed_by_us(get_absolute_time(), us), callback, user_data, fire_if_past);
}

/*!
 * \brief Add an alarm callback to be called after a delay specified in milliseconds
 * \ingroup alarm
 *
 * Generally the callback is called as soon as possible after the time specified from an IRQ handler
 * on the core the alarm pool was created on. If the callback is in the past or happens before
 * the alarm setup could be completed, then this method will optionally call the callback itself
 * and then return a return code to indicate that the target time has passed.
 *
 * \note It is safe to call this method from an IRQ handler (including alarm callbacks), and from either core.
 *
 * @param pool the alarm pool to use for scheduling the callback (this determines which hardware alarm is used, and which core calls the callback)
 * @param ms the delay (from now) in milliseconds when (after which) the callback should fire
 * @param callback the callback function
 * @param user_data user data to pass to the callback function
 * @param fire_if_past if true, and the alarm time falls before or during this call before the alarm can be set,
 *                     then the callback should be called during (by) this function instead 
 * @return >0 the alarm id
 * @return 0 if the alarm time passed before or during the call AND there is no active alarm to return the id of.
 *           The latter can either happen because fire_if_past was false (i.e. no timer was ever created),
 *           or if the callback <i>was</i> called during this method but the callback cancelled itself by returning 0
 * @return -1 if there were no alarm slots available
 */
static inline alarm_id_t alarm_pool_add_alarm_in_ms(alarm_pool_t *pool, uint32_t ms, alarm_callback_t callback, void *user_data, bool fire_if_past) {
    return alarm_pool_add_alarm_at(pool, delayed_by_ms(get_absolute_time(), ms), callback, user_data, fire_if_past);
}

/*!
 * \brief Cancel an alarm
 * \ingroup alarm
 * \param pool the alarm_pool containing the alarm
 * \param alarm_id the alarm
 * \return true if the alarm was cancelled, false if it didn't exist
 * \sa alarm_id_t for a note on reuse of IDs
 */
bool alarm_pool_cancel_alarm(alarm_pool_t *pool, alarm_id_t alarm_id);

#if !PICO_TIME_DEFAULT_ALARM_POOL_DISABLED
/*!
 * \brief Add an alarm callback to be called at a specific time
 * \ingroup alarm