[launchd-changes] [23520] trunk/launchd/src/libvproc_public.h

[source_changes at macosforge.org]

Revision: 23520
          http://trac.macosforge.org/projects/launchd/changeset/23520
Author:   zarzycki at 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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.macosforge.org/pipermail/launchd-changes/attachments/20080222/7fe562dd/attachment.html