360 lines
12 KiB
C
360 lines
12 KiB
C
/*
|
|
* Copyright (c) 2020 Apple Inc. All rights reserved.
|
|
*
|
|
* @APPLE_APACHE_LICENSE_HEADER_START@
|
|
*
|
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
* you may not use this file except in compliance with the License.
|
|
* You may obtain a copy of the License at
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*
|
|
* @APPLE_APACHE_LICENSE_HEADER_END@
|
|
*/
|
|
|
|
#ifndef __OS_WORKGROUP_OBJECT__
|
|
#define __OS_WORKGROUP_OBJECT__
|
|
|
|
#ifndef __OS_WORKGROUP_INDIRECT__
|
|
#error "Please #include <os/workgroup.h> instead of this file directly."
|
|
#include <os/workgroup_base.h> // For header doc
|
|
#endif
|
|
|
|
__BEGIN_DECLS
|
|
|
|
OS_WORKGROUP_ASSUME_NONNULL_BEGIN
|
|
OS_WORKGROUP_ASSUME_ABI_SINGLE_BEGIN
|
|
|
|
/*!
|
|
* @typedef os_workgroup_t
|
|
*
|
|
* @abstract
|
|
* A reference counted os object representing a workload that needs to
|
|
* be distinctly recognized and tracked by the system. The workgroup
|
|
* tracks a collection of threads all working cooperatively. An os_workgroup
|
|
* object - when not an instance of a specific os_workgroup_t subclass -
|
|
* represents a generic workload and makes no assumptions about the kind of
|
|
* work done.
|
|
*
|
|
* @discussion
|
|
* Threads can explicitly join an os_workgroup_t to mark themselves as
|
|
* participants in the workload.
|
|
*/
|
|
OS_WORKGROUP_DECL(os_workgroup, WorkGroup);
|
|
|
|
|
|
/* Attribute creation and specification */
|
|
|
|
/*!
|
|
* @typedef os_workgroup_attr_t
|
|
*
|
|
* @abstract
|
|
* Pointer to an opaque structure for describing attributes that can be
|
|
* configured on a workgroup at creation.
|
|
*/
|
|
typedef struct os_workgroup_attr_opaque_s os_workgroup_attr_s;
|
|
typedef struct os_workgroup_attr_opaque_s *os_workgroup_attr_t;
|
|
|
|
/* os_workgroup_t attributes need to be initialized before use. This initializer
|
|
* allows you to create a workgroup with the system default attributes. */
|
|
#define OS_WORKGROUP_ATTR_INITIALIZER_DEFAULT \
|
|
{ .sig = _OS_WORKGROUP_ATTR_SIG_DEFAULT_INIT }
|
|
|
|
|
|
|
|
/* The main use of the workgroup API is through instantiations of the concrete
|
|
* subclasses - please refer to os/workgroup_interval.h and
|
|
* os/workgroup_parallel.h for more information on creating workgroups.
|
|
*
|
|
* The functions below operate on all subclasses of os_workgroup_t.
|
|
*/
|
|
|
|
/*!
|
|
* @function os_workgroup_copy_port
|
|
*
|
|
* @abstract
|
|
* Returns a reference to a send right representing this workgroup that is to be
|
|
* sent to other processes. This port is to be passed to
|
|
* os_workgroup_create_with_port() to create a workgroup object.
|
|
*
|
|
* It is the client's responsibility to release the send right reference.
|
|
*
|
|
* If an error is encountered, errno is set and returned.
|
|
*/
|
|
API_AVAILABLE(macos(11.0))
|
|
API_UNAVAILABLE(ios, tvos, watchos)
|
|
OS_REFINED_FOR_SWIFT OS_WORKGROUP_EXPORT OS_WORKGROUP_WARN_RESULT
|
|
int
|
|
os_workgroup_copy_port(os_workgroup_t wg, mach_port_t *mach_port_out);
|
|
|
|
/*!
|
|
* @function os_workgroup_create_with_port
|
|
*
|
|
* @abstract
|
|
* Create an os_workgroup_t object from a send right returned by a previous
|
|
* call to os_workgroup_copy_port, potentially in a different process.
|
|
*
|
|
* A newly created os_workgroup_t has no initial member threads - in particular
|
|
* the creating thread does not join the os_workgroup_t implicitly.
|
|
*
|
|
* @param name
|
|
* A client specified string for labelling the workgroup. This parameter is
|
|
* optional and can be NULL.
|
|
*
|
|
* @param mach_port
|
|
* The send right to create the workgroup from. No reference is consumed
|
|
* on the specified send right.
|
|
*/
|
|
API_AVAILABLE(macos(11.0))
|
|
API_UNAVAILABLE(ios, tvos, watchos)
|
|
OS_SWIFT_NAME(WorkGroup.init(__name:port:)) OS_WORKGROUP_EXPORT OS_WORKGROUP_RETURNS_RETAINED
|
|
os_workgroup_t _Nullable
|
|
os_workgroup_create_with_port(const char *OS_WORKGROUP_UNSAFE_INDEXABLE _Nullable name, mach_port_t mach_port);
|
|
|
|
/*!
|
|
* @function os_workgroup_create_with_workgroup
|
|
*
|
|
* @abstract
|
|
* Create a new os_workgroup object from an existing os_workgroup.
|
|
*
|
|
* The newly created os_workgroup has no initial member threads - in particular
|
|
* the creating threaad does not join the os_workgroup_t implicitly.
|
|
*
|
|
* @param name
|
|
* A client specified string for labelling the workgroup. This parameter is
|
|
* optional and can be NULL.
|
|
*
|
|
* @param wg
|
|
* The existing workgroup to create a new workgroup object from.
|
|
*/
|
|
API_AVAILABLE(macos(11.0), ios(14.0), tvos(14.0), watchos(7.0))
|
|
OS_REFINED_FOR_SWIFT OS_WORKGROUP_EXPORT OS_WORKGROUP_RETURNS_RETAINED
|
|
os_workgroup_t _Nullable
|
|
os_workgroup_create_with_workgroup(const char * OS_WORKGROUP_UNSAFE_INDEXABLE _Nullable name, os_workgroup_t wg);
|
|
|
|
/*!
|
|
* @typedef os_workgroup_join_token, os_workgroup_join_token_t
|
|
*
|
|
* @abstract
|
|
* An opaque join token which the client needs to pass to os_workgroup_join
|
|
* and os_workgroup_leave
|
|
*/
|
|
OS_REFINED_FOR_SWIFT
|
|
typedef struct os_workgroup_join_token_opaque_s os_workgroup_join_token_s;
|
|
OS_REFINED_FOR_SWIFT
|
|
typedef struct os_workgroup_join_token_opaque_s *os_workgroup_join_token_t;
|
|
|
|
|
|
/*!
|
|
* @function os_workgroup_join
|
|
*
|
|
* @abstract
|
|
* Joins the current thread to the specified workgroup and populates the join
|
|
* token that has been passed in. This API is real-time safe.
|
|
*
|
|
* @param wg
|
|
* The workgroup that the current thread would like to join
|
|
*
|
|
* @param token_out
|
|
* Pointer to a client allocated struct which the function will populate
|
|
* with the join token. This token must be passed in by the thread when it calls
|
|
* os_workgroup_leave().
|
|
*
|
|
* Errors will be returned in the following cases:
|
|
*
|
|
* EALREADY The thread is already part of a workgroup that the specified
|
|
* workgroup does not nest with
|
|
* EINVAL The workgroup has been cancelled
|
|
*/
|
|
API_AVAILABLE(macos(11.0), ios(14.0), tvos(14.0), watchos(7.0))
|
|
OS_REFINED_FOR_SWIFT OS_WORKGROUP_EXPORT OS_WORKGROUP_WARN_RESULT
|
|
int
|
|
os_workgroup_join(os_workgroup_t wg, os_workgroup_join_token_t token_out);
|
|
|
|
/*!
|
|
* @function os_workgroup_leave
|
|
*
|
|
* @abstract
|
|
* This removes the current thread from a workgroup it has previously
|
|
* joined. Threads must leave all workgroups in the reverse order that they
|
|
* have joined them. Failing to do so before exiting will result in undefined
|
|
* behavior.
|
|
*
|
|
* If the join token is malformed, the process will be aborted.
|
|
*
|
|
* This API is real time safe.
|
|
*
|
|
* @param wg
|
|
* The workgroup that the current thread would like to leave.
|
|
*
|
|
* @param token
|
|
* This is the join token populated by the most recent call to
|
|
* os_workgroup_join().
|
|
*/
|
|
API_AVAILABLE(macos(11.0), ios(14.0), tvos(14.0), watchos(7.0))
|
|
OS_REFINED_FOR_SWIFT OS_WORKGROUP_EXPORT
|
|
void
|
|
os_workgroup_leave(os_workgroup_t wg, os_workgroup_join_token_t token);
|
|
|
|
/* Working Arena index of a thread in a workgroup */
|
|
typedef uint32_t os_workgroup_index;
|
|
/* Destructor for Working Arena */
|
|
typedef void (*os_workgroup_working_arena_destructor_t)(void * _Nullable);
|
|
|
|
/*!
|
|
* @function os_workgroup_set_working_arena
|
|
*
|
|
* @abstract
|
|
* Associates a client defined working arena with the workgroup. The arena
|
|
* is local to the workgroup object in the process. This is intended for
|
|
* distributing a manually managed memory allocation between member threads
|
|
* of the workgroup.
|
|
*
|
|
* This function can be called multiple times and the client specified
|
|
* destructor will be called on the previously assigned arena, if any. This
|
|
* function can only be called when no threads have currently joined the
|
|
* workgroup and all workloops associated with the workgroup are idle.
|
|
*
|
|
* @param wg
|
|
* The workgroup to associate the working arena with
|
|
*
|
|
* @param arena
|
|
* The client managed arena to associate with the workgroup. This value can
|
|
* be NULL.
|
|
*
|
|
* @param max_workers
|
|
* The maximum number of threads that will ever query the workgroup for the
|
|
* arena and request an index into it. If the arena is not used to partition
|
|
* work amongst member threads, then this field can be 0.
|
|
*
|
|
* @param destructor
|
|
* A destructor to call on the previously assigned working arena, if any
|
|
*/
|
|
API_AVAILABLE(macos(11.0), ios(14.0), tvos(14.0), watchos(7.0))
|
|
OS_REFINED_FOR_SWIFT OS_WORKGROUP_EXPORT OS_WORKGROUP_WARN_RESULT
|
|
int
|
|
os_workgroup_set_working_arena(os_workgroup_t wg, void * _Nullable arena,
|
|
uint32_t max_workers, os_workgroup_working_arena_destructor_t destructor);
|
|
|
|
/*!
|
|
* @function os_workgroup_get_working_arena
|
|
*
|
|
* @abstract
|
|
* Returns the working arena associated with the workgroup and the current
|
|
* thread's index in the workgroup. This function can only be called by a member
|
|
* of the workgroup. Multiple calls to this API by a member thread will return
|
|
* the same arena and index until the thread leaves the workgroup.
|
|
*
|
|
* For workloops with an associated workgroup, every work item on the workloop
|
|
* will receive the same index in the arena.
|
|
*
|
|
* This method returns NULL if no arena is set on the workgroup. The index
|
|
* returned by this function is zero-based and is namespaced per workgroup
|
|
* object in the process. The indices provided are strictly monotonic and never
|
|
* reused until a future call to os_workgroup_set_working_arena.
|
|
*
|
|
* @param wg
|
|
* The workgroup to get the working arena from.
|
|
*
|
|
* @param index_out
|
|
* A pointer to a os_workgroup_index which will be populated by the caller's
|
|
* index in the workgroup.
|
|
*/
|
|
API_AVAILABLE(macos(11.0), ios(14.0), tvos(14.0), watchos(7.0))
|
|
OS_REFINED_FOR_SWIFT OS_WORKGROUP_EXPORT
|
|
void * _Nullable
|
|
os_workgroup_get_working_arena(os_workgroup_t wg,
|
|
os_workgroup_index * _Nullable index_out);
|
|
|
|
/*!
|
|
* @function os_workgroup_cancel
|
|
*
|
|
* @abstract
|
|
* This API invalidates a workgroup and indicates to the system that the
|
|
* workload is no longer relevant to the caller.
|
|
*
|
|
* No new work should be initiated for a cancelled workgroup and
|
|
* work that is already underway should periodically check for
|
|
* cancellation with os_workgroup_testcancel and initiate cleanup if needed.
|
|
*
|
|
* Threads currently in the workgroup continue to be tracked together but no
|
|
* new threads may join this workgroup - the only possible operation allowed is
|
|
* to leave the workgroup. Other actions may have undefined behavior or
|
|
* otherwise fail.
|
|
*
|
|
* This API is idempotent. Cancellation is local to the workgroup object
|
|
* it is called on and does not affect other workgroups.
|
|
*
|
|
* @param wg
|
|
* The workgroup that that the thread would like to cancel
|
|
*/
|
|
API_AVAILABLE(macos(11.0), ios(14.0), tvos(14.0), watchos(7.0))
|
|
OS_REFINED_FOR_SWIFT OS_WORKGROUP_EXPORT
|
|
void
|
|
os_workgroup_cancel(os_workgroup_t wg);
|
|
|
|
/*!
|
|
* @function os_workgroup_testcancel
|
|
*
|
|
* @abstract
|
|
* Returns true if the workgroup object has been cancelled. See also
|
|
* os_workgroup_cancel
|
|
*/
|
|
API_AVAILABLE(macos(11.0), ios(14.0), tvos(14.0), watchos(7.0))
|
|
OS_REFINED_FOR_SWIFT OS_WORKGROUP_EXPORT
|
|
bool
|
|
os_workgroup_testcancel(os_workgroup_t wg);
|
|
|
|
/*!
|
|
* @typedef os_workgroup_max_parallel_threads_attr_t
|
|
*
|
|
* @abstract
|
|
* A pointer to a structure describing the set of properties of a workgroup to
|
|
* override with the explicitly specified values in the structure.
|
|
*
|
|
* See also os_workgroup_max_parallel_threads.
|
|
*/
|
|
OS_REFINED_FOR_SWIFT
|
|
typedef struct os_workgroup_max_parallel_threads_attr_s os_workgroup_mpt_attr_s;
|
|
OS_REFINED_FOR_SWIFT
|
|
typedef struct os_workgroup_max_parallel_threads_attr_s *os_workgroup_mpt_attr_t;
|
|
|
|
/*!
|
|
* @function os_workgroup_max_parallel_threads
|
|
*
|
|
* @abstract
|
|
* Returns the system's recommendation for maximum number of threads the client
|
|
* should make for a multi-threaded workload in a given workgroup.
|
|
*
|
|
* This API takes into consideration the current hardware the code is running on
|
|
* and the attributes of the workgroup. It does not take into consideration the
|
|
* current load of the system and therefore always provides the most optimal
|
|
* recommendation for the workload.
|
|
*
|
|
* @param wg
|
|
* The workgroup in which the multi-threaded workload will be performed in. The
|
|
* threads performing the multi-threaded workload are expected to join this
|
|
* workgroup.
|
|
*
|
|
* @param attr
|
|
* This value is currently unused and should be NULL.
|
|
*/
|
|
API_AVAILABLE(macos(11.0), ios(14.0), tvos(14.0), watchos(7.0))
|
|
OS_REFINED_FOR_SWIFT OS_WORKGROUP_EXPORT
|
|
int
|
|
os_workgroup_max_parallel_threads(os_workgroup_t wg, os_workgroup_mpt_attr_t
|
|
_Nullable attr);
|
|
|
|
OS_WORKGROUP_ASSUME_ABI_SINGLE_END
|
|
OS_WORKGROUP_ASSUME_NONNULL_END
|
|
|
|
__END_DECLS
|
|
|
|
#endif /* __OS_WORKGROUP_OBJECT__ */
|