| | 37 | /*! |
| | 38 | * @header vproc |
| | 39 | * |
| | 40 | * Processes have two reference counts associated with them: |
| | 41 | * |
| | 42 | * Dirty Tracks dirty data that needs to be flushed later. |
| | 43 | * Standby Tracks any case where future work is expected. |
| | 44 | * |
| | 45 | * Processes that have no dirty data are called "clean." |
| | 46 | * Processes that are not standing by are called "idle." |
| | 47 | * |
| | 48 | * These two reference counts are used to prevent the application from |
| | 49 | * prematurely exiting. |
| | 50 | * |
| | 51 | * Sometimes, the operating system needs processes to exit. Unix has two |
| | 52 | * primary signals to kill applications: |
| | 53 | * |
| | 54 | * SIGKILL Not catchable by the application. |
| | 55 | * SIGTERM Catchable by the application. |
| | 56 | * |
| | 57 | * If a process is clean, the operating system is free to SIGKILL it at |
| | 58 | * shutdown or logout. |
| | 59 | * |
| | 60 | * If a process is clean and idle, the operating system may send SIGKILL after |
| | 61 | * a application specified timeout. |
| | 62 | * |
| | 63 | * If a process is dirty and idle, the operating system may send SIGTERM after |
| | 64 | * a application specified timeout. |
| | 65 | * |
| | 66 | * |
| | 67 | * launchd jobs should update their property lists accordingly. |
| | 68 | * |
| | 69 | * LaunchServicese uses private API to coordinate whether GUI applications |
| | 70 | * have opted into this design. |
| | 71 | */ |
| | 72 | |
| | 73 | /*! |
| | 74 | * @function vproc_dirty_retain |
| | 75 | * |
| | 76 | * @abstract |
| | 77 | * Call this API before creating data that needs to be saved via I/O later. |
| | 78 | */ |
| | 79 | void |
| | 80 | vproc_dirty_retain(void); |
| | 81 | |
| | 82 | /*! |
| | 83 | * @function vproc_dirty_release |
| | 84 | * |
| | 85 | * @abstract |
| | 86 | * Call this API after the dirty data has either been flushed or otherwise resolved. |
| | 87 | */ |
| | 88 | void |
| | 89 | vproc_dirty_release(void); |
| | 90 | |
| | 91 | /*! |
| | 92 | * @function vproc_dirty_count |
| | 93 | * |
| | 94 | * @result |
| | 95 | * Zero if the program is clean. Non-zero if the program contains dirty data. |
| | 96 | * |
| | 97 | * @abstract |
| | 98 | * A simple API to discover whether the program is dirty or not. |
| | 99 | */ |
| | 100 | size_t |
| | 101 | vproc_dirty_count(void); |
| | 102 | |
| | 103 | /*! |
| | 104 | * @function vproc_standby_retain |
| | 105 | * |
| | 106 | * @abstract |
| | 107 | * Call this API when registering notfications. For example: timers network |
| | 108 | * state change, or when monitoring keyboard/mouse events. |
| | 109 | */ |
| | 110 | void vproc_standby_retain(void); |
| | 111 | |
| | 112 | /*! |
| | 113 | * @function vproc_standby_release |
| | 114 | * |
| | 115 | * @abstract |
| | 116 | * Call this API when deregistering notfications. |
| | 117 | */ |
| | 118 | void vproc_standby_release(void); |
| | 119 | |
| | 120 | /*! |
| | 121 | * @function vproc_standby_count |
| | 122 | * |
| | 123 | * @result |
| | 124 | * Zero if the program is idle. Non-zero if the program contains outstanding event sources registered. |
| | 125 | * |
| | 126 | * @abstract |
| | 127 | * A simple API to discover whether the program is idle or not. |
| | 128 | */ |
| | 129 | size_t |
| | 130 | size_t vproc_standby_count(void); |
| | 131 | |
