Revision: 23520 http://trac.macosforge.org/projects/launchd/changeset/23520 Author: zarzycki@apple.com Date: 2008-02-22 13:22:29 -0800 (Fri, 22 Feb 2008) Log Message: ----------- Note to self. A design we are considering. Modified Paths: -------------- trunk/launchd/src/libvproc_public.h Modified: trunk/launchd/src/libvproc_public.h =================================================================== --- trunk/launchd/src/libvproc_public.h 2008-02-20 20:36:39 UTC (rev 23519) +++ trunk/launchd/src/libvproc_public.h 2008-02-22 21:22:29 UTC (rev 23520) @@ -34,6 +34,101 @@ const char *vproc_strerror(vproc_err_t r); +/*! + * @header vproc + * + * Processes have two reference counts associated with them: + * + * Dirty Tracks dirty data that needs to be flushed later. + * Standby Tracks any case where future work is expected. + * + * Processes that have no dirty data are called "clean." + * Processes that are not standing by are called "idle." + * + * These two reference counts are used to prevent the application from + * prematurely exiting. + * + * Sometimes, the operating system needs processes to exit. Unix has two + * primary signals to kill applications: + * + * SIGKILL Not catchable by the application. + * SIGTERM Catchable by the application. + * + * If a process is clean, the operating system is free to SIGKILL it at + * shutdown or logout. + * + * If a process is clean and idle, the operating system may send SIGKILL after + * a application specified timeout. + * + * If a process is dirty and idle, the operating system may send SIGTERM after + * a application specified timeout. + * + * + * launchd jobs should update their property lists accordingly. + * + * LaunchServicese uses private API to coordinate whether GUI applications + * have opted into this design. + */ + +/*! + * @function vproc_dirty_retain + * + * @abstract + * Call this API before creating data that needs to be saved via I/O later. + */ +void +vproc_dirty_retain(void); + +/*! + * @function vproc_dirty_release + * + * @abstract + * Call this API after the dirty data has either been flushed or otherwise resolved. + */ +void +vproc_dirty_release(void); + +/*! + * @function vproc_dirty_count + * + * @result + * Zero if the program is clean. Non-zero if the program contains dirty data. + * + * @abstract + * A simple API to discover whether the program is dirty or not. + */ +size_t +vproc_dirty_count(void); + +/*! + * @function vproc_standby_retain + * + * @abstract + * Call this API when registering notfications. For example: timers network + * state change, or when monitoring keyboard/mouse events. + */ +void vproc_standby_retain(void); + +/*! + * @function vproc_standby_release + * + * @abstract + * Call this API when deregistering notfications. + */ +void vproc_standby_release(void); + +/*! + * @function vproc_standby_count + * + * @result + * Zero if the program is idle. Non-zero if the program contains outstanding event sources registered. + * + * @abstract + * A simple API to discover whether the program is idle or not. + */ +size_t +size_t vproc_standby_count(void); + #pragma GCC visibility pop __END_DECLS