workgroup_interval.h (5690B) - Raw
1 /* 2 * Copyright (c) 2020 Apple Inc. All rights reserved. 3 * 4 * @APPLE_APACHE_LICENSE_HEADER_START@ 5 * 6 * Licensed under the Apache License, Version 2.0 (the "License"); 7 * you may not use this file except in compliance with the License. 8 * You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, software 13 * distributed under the License is distributed on an "AS IS" BASIS, 14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 * See the License for the specific language governing permissions and 16 * limitations under the License. 17 * 18 * @APPLE_APACHE_LICENSE_HEADER_END@ 19 */ 20 21 #ifndef __OS_WORKGROUP_INTERVAL__ 22 #define __OS_WORKGROUP_INTERVAL__ 23 24 #ifndef __OS_WORKGROUP_INDIRECT__ 25 #error "Please #include <os/workgroup.h> instead of this file directly." 26 #include <os/workgroup_base.h> // For header doc 27 #endif 28 29 __BEGIN_DECLS 30 31 OS_WORKGROUP_ASSUME_NONNULL_BEGIN 32 OS_WORKGROUP_ASSUME_ABI_SINGLE_BEGIN 33 34 /*! 35 * @typedef os_workgroup_interval_t 36 * 37 * @abstract 38 * A subclass of an os_workgroup_t for tracking work performed as part of 39 * a repeating interval-driven workload. 40 */ 41 OS_WORKGROUP_SUBCLASS_DECL_PROTO(os_workgroup_interval, Repeatable); 42 OS_WORKGROUP_SUBCLASS_DECL(os_workgroup_interval, os_workgroup, WorkGroupInterval); 43 44 /* During the first instance of this API, the only supported interval 45 * workgroups are for audio workloads. Please refer to the AudioToolbox 46 * framework for more information. 47 */ 48 49 /* 50 * @typedef os_workgroup_interval_data, os_workgroup_interval_data_t 51 * 52 * @abstract 53 * An opaque structure containing additional configuration for the workgroup 54 * interval. 55 */ 56 typedef struct os_workgroup_interval_data_opaque_s os_workgroup_interval_data_s; 57 typedef struct os_workgroup_interval_data_opaque_s *os_workgroup_interval_data_t; 58 #define OS_WORKGROUP_INTERVAL_DATA_INITIALIZER \ 59 { .sig = _OS_WORKGROUP_INTERVAL_DATA_SIG_INIT } 60 61 /*! 62 * @function os_workgroup_interval_start 63 * 64 * @abstract 65 * Indicates to the system that the member threads of this 66 * os_workgroup_interval_t have begun working on an instance of the repeatable 67 * interval workload with the specified timestamps. This function is real time 68 * safe. 69 * 70 * This function will set and return an errno in the following cases: 71 * 72 * - The current thread is not a member of the os_workgroup_interval_t 73 * - The os_workgroup_interval_t has been cancelled 74 * - The timestamps passed in are malformed 75 * - os_workgroup_interval_start() was previously called on the 76 * os_workgroup_interval_t without an intervening os_workgroup_interval_finish() 77 * - A concurrent workgroup interval configuration operation is taking place. 78 * 79 * @param start 80 * Start timestamp specified in the os_clockid_t with which the 81 * os_workgroup_interval_t was created. This is generally a time in the past and 82 * indicates when the workgroup started working on an interval period 83 * 84 * @param deadline 85 * Deadline timestamp specified in the os_clockid_t with which the 86 * os_workgroup_interval_t was created. This specifies the deadline which the 87 * interval period would like to meet. 88 * 89 * @param data 90 * This field is currently unused and should be NULL 91 */ 92 API_AVAILABLE(macos(11.0), ios(14.0), tvos(14.0), watchos(7.0)) 93 OS_REFINED_FOR_SWIFT OS_WORKGROUP_EXPORT OS_WORKGROUP_WARN_RESULT 94 int 95 os_workgroup_interval_start(os_workgroup_interval_t wg, uint64_t start, uint64_t 96 deadline, os_workgroup_interval_data_t _Nullable data); 97 98 /*! 99 * @function os_workgroup_interval_update 100 * 101 * @abstract 102 * Updates an already started workgroup interval to have the new 103 * deadline specified. This function is real time safe. 104 * 105 * This function will return an error in the following cases: 106 * - The current thread is not a member of the os_workgroup_interval_t 107 * - The os_workgroup_interval_t has been cancelled 108 * - The timestamp passed in is malformed 109 * - os_workgroup_interval_start() was not previously called on the 110 * os_workgroup_interval_t or was already matched with an 111 * os_workgroup_interval_finish() 112 * - A concurrent workgroup interval configuration operation is taking place 113 * 114 * @param deadline 115 * Timestamp specified in the os_clockid_t with 116 * which the os_workgroup_interval_t was created. 117 * 118 * @param data 119 * This field is currently unused and should be NULL 120 */ 121 API_AVAILABLE(macos(11.0), ios(14.0), tvos(14.0), watchos(7.0)) 122 OS_REFINED_FOR_SWIFT OS_WORKGROUP_EXPORT OS_WORKGROUP_WARN_RESULT 123 int 124 os_workgroup_interval_update(os_workgroup_interval_t wg, uint64_t deadline, 125 os_workgroup_interval_data_t _Nullable data); 126 127 /*! 128 * @function os_workgroup_interval_finish 129 * 130 * @abstract 131 * Indicates to the system that the member threads of 132 * this os_workgroup_interval_t have finished working on the current instance 133 * of the interval workload. This function is real time safe. 134 * 135 * This function will return an error in the following cases: 136 * - The current thread is not a member of the os_workgroup_interval_t 137 * - os_workgroup_interval_start() was not previously called on the 138 * os_workgroup_interval_t or was already matched with an 139 * os_workgroup_interval_finish() 140 * - A concurrent workgroup interval configuration operation is taking place. 141 * 142 * @param data 143 * This field is currently unused and should be NULL 144 */ 145 API_AVAILABLE(macos(11.0), ios(14.0), tvos(14.0), watchos(7.0)) 146 OS_REFINED_FOR_SWIFT OS_WORKGROUP_EXPORT OS_WORKGROUP_WARN_RESULT 147 int 148 os_workgroup_interval_finish(os_workgroup_interval_t wg, 149 os_workgroup_interval_data_t _Nullable data); 150 151 OS_WORKGROUP_ASSUME_ABI_SINGLE_END 152 OS_WORKGROUP_ASSUME_NONNULL_END 153 154 __END_DECLS 155 156 #endif /* __OS_WORKGROUP_INTERVAL__ */