liblaunch/vproc.h

   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__ */