1 /* 2 * Copyright (c) 2006 Apple Computer, 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 __VPROC_H__ 22 #define __VPROC_H__ 23 24 #include <sys/cdefs.h> 25 #include <sys/types.h> 26 #include <Availability.h> 27 28 #ifndef VPROC_HAS_TRANSACTIONS 29 #define VPROC_HAS_TRANSACTIONS 30 #endif 31 32 __BEGIN_DECLS 33 34 #pragma GCC visibility push(default) 35 36 typedef void * vproc_err_t; 37 38 typedef struct vproc_s * vproc_t; 39 typedef void * vprocmgr_t; 40 41 const char *vproc_strerror(vproc_err_t r); 42 43 /*! 44 * @header vproc 45 * 46 * Processes have two reference counts associated with them: 47 * 48 * Transactions Tracks unfinished work. For example: saving a modified 49 * document. 50 * Standby Tracks outstanding callbacks from external subsystems. 51 * 52 * Descriptive aliases: 53 * 54 * A process with no outstanding transactions is called "clean." 55 * A process with outstanding transactions is called "dirty." 56 * A process with no standby work is called "idle." 57 * 58 * Sometimes, the operating system needs processes to exit. Unix has two 59 * primary signals to kill applications: 60 * 61 * SIGKILL Not catchable by the application. 62 * SIGTERM Catchable by the application. 63 * 64 * If a process is clean, the operating system is free to SIGKILL it at 65 * shutdown or logout. This behavior is opt in. 66 * 67 * If a process is clean and idle, the operating system may send SIGKILL after 68 * a application specified timeout. This behavior is opt in. 69 * 70 * If a process is dirty and idle, the operating system may send SIGTERM after 71 * a application specified timeout. This behavior is opt in. 72 * 73 * 74 * launchd jobs should update their property lists accordingly. 75 * 76 * We plan to have LaunchServices use private methods to coordinate 77 * whether GUI applications have opted into this design. 78 */ 79 80 /*! 81 * @typedef vproc_transaction_t 82 * 83 * @abstract 84 * An opaque handle used to track outstanding transactions. 85 */ 86 typedef struct vproc_transaction_s *vproc_transaction_t; 87 88 /*! 89 * @function vproc_transaction_begin 90 * 91 * @param virtual_proc 92 * This is meant for future API improvements. Pass NULL for now. 93 * 94 * @result 95 * Returns an opaque handle to be passed to vproc_transaction_end(). 96 * 97 * @abstract 98 * Call this API before creating data that needs to be saved via I/O later. 99 */ 100 vproc_transaction_t 101 vproc_transaction_begin(vproc_t virtual_proc) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_5_0); 102 103 /*! 104 * @function vproc_transaction_end 105 * 106 * @param virtual_proc 107 * This is meant for future API improvements. Pass NULL for now. 108 * 109 * @param handle 110 * The handle previously created with vproc_transaction_begin(). 111 * 112 * @abstract 113 * Call this API after the data has either been flushed or otherwise resolved. 114 * 115 * @discussion 116 * Calling this API with the same handle more than once is undefined. 117 */ 118 void 119 vproc_transaction_end(vproc_t virtual_proc, vproc_transaction_t handle) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_5_0); 120 121 /*! 122 * @typedef vproc_standby_t 123 * 124 * @abstract 125 * An opaque handle used to track outstanding standby requests. 126 */ 127 typedef struct vproc_standby_s *vproc_standby_t; 128 129 /*! 130 * @function vproc_standby_begin 131 * 132 * @param virtual_proc 133 * This is meant for future API improvements. Pass NULL for now. 134 * 135 * @result 136 * Returns an opaque handle to be passed to vproc_standby_end(). 137 * 138 * @abstract 139 * Call this API before registering notifications. For example: timers network 140 * state change, or when monitoring keyboard/mouse events. 141 * 142 * @discussion 143 * This API is undefined and is currently a no-op. 144 */ 145 vproc_standby_t 146 vproc_standby_begin(vproc_t virtual_proc) __OSX_AVAILABLE_STARTING(__MAC_NA, __IPHONE_NA); 147 148 /*! 149 * @function vproc_standby_end 150 * 151 * @param virtual_proc 152 * This is meant for future API improvements. Pass NULL for now. 153 * 154 * @param handle 155 * The handle previously created with vproc_standby_begin(). 156 * 157 * @abstract 158 * Call this API when deregistering notifications. 159 * 160 * @discussion 161 * Calling this API with the same handle more than once is undefined. 162 * This API is undefined and is currently a no-op. 163 */ 164 void 165 vproc_standby_end(vproc_t virtual_proc, vproc_standby_t handle) __OSX_AVAILABLE_STARTING(__MAC_NA, __IPHONE_NA); 166 167 #pragma GCC visibility pop 168 169 __END_DECLS 170 171 #endif /* __VPROC_H__ */ 172