include/android_stub/ndk/sync.h

   1 /*
   2  *  Copyright 2017 The Android Open Source Project
   3  *
   4  *  Licensed under the Apache License, Version 2.0 (the "License");
   5  *  you may not use this file except in compliance with the License.
   6  *  You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  *  Unless required by applicable law or agreed to in writing, software
  11  *  distributed under the License is distributed on an "AS IS" BASIS,
  12  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  *  See the License for the specific language governing permissions and
  14  *  limitations under the License.
  15  */
  16
  17 /**
  18  * @addtogroup Sync
  19  * @{
  20  */
  21
  22 /**
  23  * @file sync.h
  24  */
  25
  26 #ifndef ANDROID_SYNC_H
  27 #define ANDROID_SYNC_H
  28
  29 #include <stdint.h>
  30 #include <sys/cdefs.h>
  31
  32 #include <linux/sync_file.h>
  33
  34 __BEGIN_DECLS
  35
  36 #if __ANDROID_API__ >= 26
  37
  38 /* Fences indicate the status of an asynchronous task. They are initially
  39  * in unsignaled state (0), and make a one-time transition to either signaled
  40  * (1) or error (< 0) state. A sync file is a collection of one or more fences;
  41  * the sync file's status is error if any of its fences are in error state,
  42  * signaled if all of the child fences are signaled, or unsignaled otherwise.
  43  *
  44  * Sync files are created by various device APIs in response to submitting
  45  * tasks to the device. Standard file descriptor lifetime syscalls like dup()
  46  * and close() are used to manage sync file lifetime.
  47  *
  48  * The poll(), ppoll(), or select() syscalls can be used to wait for the sync
  49  * file to change status, or (with a timeout of zero) to check its status.
  50  *
  51  * The functions below provide a few additional sync-specific operations.
  52  */
  53
  54 /**
  55  * Merge two sync files.
  56  *
  57  * This produces a new sync file with the given name which has the union of the
  58  * two original sync file's fences; redundant fences may be removed.
  59  *
  60  * If one of the input sync files is signaled or invalid, then this function
  61  * may behave like dup(): the new file descriptor refers to the valid/unsignaled
  62  * sync file with its original name, rather than a new sync file.
  63  *
  64  * The original fences remain valid, and the caller is responsible for closing
  65  * them.
  66  *
  67  * Available since API level 26.
  68  */
  69 int32_t sync_merge(const char* name, int32_t fd1, int32_t fd2) __INTRODUCED_IN(26);
  70
  71 /**
  72  * Retrieve detailed information about a sync file and its fences.
  73  *
  74  * The returned sync_file_info must be freed by calling sync_file_info_free().
  75  *
  76  * Available since API level 26.
  77  */
  78 struct sync_file_info* sync_file_info(int32_t fd) __INTRODUCED_IN(26);
  79
  80 /**
  81  * Get the array of fence infos from the sync file's info.
  82  *
  83  * The returned array is owned by the parent sync file info, and has
  84  * info->num_fences entries.
  85  *
  86  * Available since API level 26.
  87  */
  88 static inline struct sync_fence_info* sync_get_fence_info(const struct sync_file_info* info) {
  89 // This header should compile in C, but some C++ projects enable
  90 // warnings-as-error for C-style casts.
  91 #pragma GCC diagnostic push
  92 #pragma GCC diagnostic ignored "-Wold-style-cast"
  93     return (struct sync_fence_info *)(uintptr_t)(info->sync_fence_info);
  94 #pragma GCC diagnostic pop
  95 }
  96
  97 /**
  98  * Free a struct sync_file_info structure
  99  *
 100  * Available since API level 26.
 101  */
 102 void sync_file_info_free(struct sync_file_info* info) __INTRODUCED_IN(26);
 103
 104 #endif /* __ANDROID_API__ >= 26 */
 105
 106 __END_DECLS
 107
 108 #endif /* ANDROID_SYNC_H */
 109
 110 /** @} */