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

[source_changes at macosforge.org]

Revision: 23522
          http://trac.macosforge.org/projects/launchd/changeset/23522
Author:   zarzycki at apple.com
Date:     2008-02-25 11:42:03 -0800 (Mon, 25 Feb 2008)

Log Message:
-----------
Incorporated feedback.

Modified Paths:
--------------
    trunk/launchd/src/libvproc_public.h

Modified: trunk/launchd/src/libvproc_public.h
===================================================================
--- trunk/launchd/src/libvproc_public.h	2008-02-22 21:27:25 UTC (rev 23521)
+++ trunk/launchd/src/libvproc_public.h	2008-02-25 19:42:03 UTC (rev 23522)
@@ -39,14 +39,15 @@
  *
  * 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.
+ * Transactions Tracks unfinished work. For example: saving a modified
+ *		document.
+ * Standby	Tracks outstanding callbacks from external subsystems.
  *
- * Processes that have no dirty data are called "clean."
- * Processes that are not standing by are called "idle."
+ * Descriptive aliases:
  *
- * These two reference counts are used to prevent the application from
- * prematurely exiting.
+ * A process with no outstanding transactions is called "clean."
+ * A process with outstanding transactions is called "dirty."
+ * A process with no standby work is called "idle."
  *
  * Sometimes, the operating system needs processes to exit. Unix has two
  * primary signals to kill applications:
@@ -55,79 +56,69 @@
  * SIGTERM	Catchable by the application.
  *
  * If a process is clean, the operating system is free to SIGKILL it at
- * shutdown or logout.
+ * shutdown or logout. This behavior is opt in.
  *
  * If a process is clean and idle, the operating system may send SIGKILL after
- * a application specified timeout.
+ * a application specified timeout. This behavior is opt in.
  *
  * If a process is dirty and idle, the operating system may send SIGTERM after
- * a application specified timeout.
+ * a application specified timeout. This behavior is opt in.
  *
  *
  * launchd jobs should update their property lists accordingly.
  *
- * LaunchServicese uses private API to coordinate whether GUI applications
+ * LaunchServices uses private API to coordinate whether GUI applications
  * have opted into this design.
  */
 
 /*!
- * @function vproc_dirty_retain
+ * @function vproc_transaction_prepare
  *
+ * @result
+ * Returns an opaque handle to be passed to vproc_transaction_complete().
+ *
  * @abstract
  * Call this API before creating data that needs to be saved via I/O later.
  */
-void
-vproc_dirty_retain(void);
+void *
+vproc_transaction_prepare(void);
 
 /*!
- * @function vproc_dirty_release
+ * @function vproc_transaction_complete
  *
+ * @param
+ * The handle previously created with vproc_transaction_prepare().
+ *
  * @abstract
- * Call this API after the dirty data has either been flushed or otherwise resolved.
+ * Call this API after the data has either been flushed or otherwise resolved.
+ *
+ * @discussion
+ * Calling this API with the same handle more than once is undefined.
  */
 void
-vproc_dirty_release(void);
+vproc_transaction_complete(void *handle);
 
 /*!
- * @function vproc_dirty_count
+ * @function vproc_standby_prepare
  *
- * @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 notifications. For example: timers network
+ * Call this API before registering notifications. For example: timers network
  * state change, or when monitoring keyboard/mouse events.
  */
-void vproc_standby_retain(void);
+void *
+vproc_standby_prepare(void);
 
 /*!
- * @function vproc_standby_release
+ * @function vproc_standby_complete
  *
  * @abstract
  * Call this API when deregistering notifications.
- */
-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.
+ * @discussion
+ * Calling this API with the same handle more than once is undefined.
  */
-size_t
-size_t vproc_standby_count(void);
+void
+vproc_standby_complete(void *handle);
 
 #pragma GCC visibility pop
 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.macosforge.org/pipermail/launchd-changes/attachments/20080225/431fb075/attachment.html