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
 31OS_WORKGROUP_ASSUME_NONNULL_BEGIN
 32OS_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 */
 41OS_WORKGROUP_SUBCLASS_DECL_PROTO(os_workgroup_interval, Repeatable);
 42OS_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 */
 56typedef struct os_workgroup_interval_data_opaque_s os_workgroup_interval_data_s;
 57typedef 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 */
 92API_AVAILABLE(macos(11.0), ios(14.0), tvos(14.0), watchos(7.0))
 93OS_REFINED_FOR_SWIFT OS_WORKGROUP_EXPORT OS_WORKGROUP_WARN_RESULT
 94int
 95os_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 */
121API_AVAILABLE(macos(11.0), ios(14.0), tvos(14.0), watchos(7.0))
122OS_REFINED_FOR_SWIFT OS_WORKGROUP_EXPORT OS_WORKGROUP_WARN_RESULT
123int
124os_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 */
145API_AVAILABLE(macos(11.0), ios(14.0), tvos(14.0), watchos(7.0))
146OS_REFINED_FOR_SWIFT OS_WORKGROUP_EXPORT OS_WORKGROUP_WARN_RESULT
147int
148os_workgroup_interval_finish(os_workgroup_interval_t wg,
149		os_workgroup_interval_data_t _Nullable data);
150
151OS_WORKGROUP_ASSUME_ABI_SINGLE_END
152OS_WORKGROUP_ASSUME_NONNULL_END
153
154__END_DECLS
155
156#endif /* __OS_WORKGROUP_INTERVAL__ */