OSX/utilities/sec_action.h

   1 /*
   2  * Copyright (c) 2017 Apple Inc. All Rights Reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 #ifndef _SEC_ACTION_H_
  25 #define _SEC_ACTION_H_
  26
  27 #include <dispatch/dispatch.h>
  28
  29 /*
  30  * Simple dispatch-based mechanism to coalesce high-frequency actions like
  31  * notifications. Sample usage:
  32  *
  33  *  static void
  34  *  notify_frequent_event(void)
  35  *  {
  36  *      static dispatch_once_t once;
  37  *      static sec_action_t action;
  38  *
  39  *      dispatch_once(&once, ^{
  40  *          action = sec_action_create("frequent_event", 2);
  41  *          sec_action_set_handler(action, ^{
  42  *              (void)notify_post("com.apple.frequent_event");
  43  *          });
  44  *      });
  45  *
  46  *      sec_action_perform(action);
  47  *  }
  48  *
  49  * The above will prevent com.apple.frequent_event from being posted more than
  50  * once every 2 seconds. For example, if notify_frequent_event is called 1000 times
  51  * over the span of 1.9s, the handler will be called twice, at 0s and 2s (approx).
  52  *
  53  * Default behavior is to perform actions on a queue with the same QOS as the caller.
  54  * If the action should be performed on a specific serial queue, the function
  55  * sec_action_create_with_queue can alternatively be used.
  56  */
  57
  58 typedef dispatch_source_t sec_action_t;
  59
  60 __BEGIN_DECLS
  61
  62 DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
  63 sec_action_t
  64 sec_action_create(const char *label, uint64_t interval);
  65
  66 DISPATCH_MALLOC DISPATCH_RETURNS_RETAINED DISPATCH_WARN_RESULT DISPATCH_NOTHROW
  67 sec_action_t
  68 sec_action_create_with_queue(dispatch_queue_t queue, const char *label, uint64_t interval);
  69
  70 DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
  71 void
  72 sec_action_set_handler(sec_action_t action, dispatch_block_t handler);
  73
  74 DISPATCH_NONNULL_ALL
  75 void
  76 sec_action_perform(sec_action_t action);
  77
  78 __END_DECLS
  79
  80 #endif /* _SEC_ACTION_H_ */