keychain/ckks/CKKSNearFutureScheduler.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 #if OCTAGON
  25
  26 #import <Foundation/Foundation.h>
  27 #import <dispatch/dispatch.h>
  28 #import <keychain/ckks/CKKSResultOperation.h>
  29
  30 NS_ASSUME_NONNULL_BEGIN
  31
  32 /*
  33  * The CKKSNearFutureScheduler is intended to rate-limit an operation. When
  34  * triggered, it will schedule the operation to take place in the future.
  35  * Further triggers during the delay period will not cause the operation to
  36  * occur again, but they may cause the delay period to extend.
  37  *
  38  * Triggers after the delay period will start another delay period.
  39  */
  40
  41 @interface CKKSNearFutureScheduler : NSObject
  42
  43 @property (nullable, readonly) NSDate* nextFireTime;
  44 @property void (^futureBlock)(void);
  45
  46 // Will execute every time futureBlock is called, just after the future block.
  47 // Operations added in the futureBlock will receive the next operationDependency, so they won't run again until futureBlock occurs again.
  48 @property (readonly) CKKSResultOperation* operationDependency;
  49
  50
  51 // dependencyDescriptionCode will be integrated into the operationDependency as per the rules in CKKSResultOperation.h
  52 - (instancetype)initWithName:(NSString*)name
  53                        delay:(dispatch_time_t)ns
  54             keepProcessAlive:(bool)keepProcessAlive
  55    dependencyDescriptionCode:(NSInteger)code
  56                        block:(void (^_Nonnull)(void))futureBlock;
  57
  58 - (instancetype)initWithName:(NSString*)name
  59                 initialDelay:(dispatch_time_t)initialDelay
  60              continuingDelay:(dispatch_time_t)continuingDelay
  61             keepProcessAlive:(bool)keepProcessAlive
  62    dependencyDescriptionCode:(NSInteger)code
  63                        block:(void (^_Nonnull)(void))futureBlock;
  64
  65 - (instancetype)initWithName:(NSString*)name
  66                 initialDelay:(dispatch_time_t)initialDelay
  67             expontialBackoff:(double)backoff
  68                 maximumDelay:(dispatch_time_t)maximumDelay
  69             keepProcessAlive:(bool)keepProcessAlive
  70    dependencyDescriptionCode:(NSInteger)code
  71                        block:(void (^_Nonnull)(void))futureBlock;
  72
  73 - (void)trigger;
  74
  75 - (void)cancel;
  76
  77 // Don't trigger again until at least this much time has passed.
  78 - (void)waitUntil:(uint64_t)delay;
  79
  80 // Trigger at this time (unless further instructions are given)
  81 - (void)triggerAt:(uint64_t)delay;
  82
  83 - (void)changeDelays:(dispatch_time_t)initialDelay continuingDelay:(dispatch_time_t)continuingDelay;
  84
  85 // tests
  86 @property CKKSCondition* liveRequestReceived;
  87
  88 @end
  89
  90 NS_ASSUME_NONNULL_END
  91 #endif // OCTAGON