launchd/src/vproc.h

   1 #ifndef _VPROC_H_
   2 #define _VPROC_H_
   3 /*
   4  * Copyright (c) 2006 Apple Computer, Inc. All rights reserved.
   5  *
   6  * @APPLE_APACHE_LICENSE_HEADER_START@
   7  *
   8  * Licensed under the Apache License, Version 2.0 (the "License");
   9  * you may not use this file except in compliance with the License.
  10  * You may obtain a copy of the License at
  11  *
  12  *     http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing, software
  15  * distributed under the License is distributed on an "AS IS" BASIS,
  16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  * See the License for the specific language governing permissions and
  18  * limitations under the License.
  19  *
  20  * @APPLE_APACHE_LICENSE_HEADER_END@
  21  */
  22
  23 #include <sys/cdefs.h>
  24 #include <sys/types.h>
  25 #include <Availability.h>
  26
  27 #ifndef VPROC_HAS_TRANSACTIONS
  28         #define VPROC_HAS_TRANSACTIONS
  29 #endif
  30
  31 __BEGIN_DECLS
  32
  33 #pragma GCC visibility push(default)
  34
  35 typedef void * vproc_err_t;
  36
  37 typedef struct vproc_s * vproc_t;
  38 typedef void * vprocmgr_t;
  39
  40 const char *vproc_strerror(vproc_err_t r);
  41
  42 /*!
  43  * @header      vproc
  44  *
  45  * Processes have two reference counts associated with them:
  46  *
  47  * Transactions Tracks unfinished work. For example: saving a modified
  48  *              document.
  49  * Standby      Tracks outstanding callbacks from external subsystems.
  50  *
  51  * Descriptive aliases:
  52  *
  53  * A process with no outstanding transactions is called "clean."
  54  * A process with outstanding transactions is called "dirty."
  55  * A process with no standby work is called "idle."
  56  *
  57  * Sometimes, the operating system needs processes to exit. Unix has two
  58  * primary signals to kill applications:
  59  *
  60  * SIGKILL      Not catchable by the application.
  61  * SIGTERM      Catchable by the application.
  62  *
  63  * If a process is clean, the operating system is free to SIGKILL it at
  64  * shutdown or logout. This behavior is opt in.
  65  *
  66  * If a process is clean and idle, the operating system may send SIGKILL after
  67  * a application specified timeout. This behavior is opt in.
  68  *
  69  * If a process is dirty and idle, the operating system may send SIGTERM after
  70  * a application specified timeout. This behavior is opt in.
  71  *
  72  *
  73  * launchd jobs should update their property lists accordingly.
  74  *
  75  * We plan to have LaunchServices use private methods to coordinate
  76  * whether GUI applications have opted into this design.
  77  */
  78
  79 /*!
  80  * @typedef     vproc_transaction_t
  81  *
  82  * @abstract
  83  * An opaque handle used to track outstanding transactions.
  84  */
  85 typedef struct vproc_transaction_s *vproc_transaction_t;
  86
  87 /*!
  88  * @function vproc_transaction_begin
  89  *
  90  * @param       virtual_proc
  91  * This is meant for future API improvements. Pass NULL for now.
  92  *
  93  * @result
  94  * Returns an opaque handle to be passed to vproc_transaction_end().
  95  *
  96  * @abstract
  97  * Call this API before creating data that needs to be saved via I/O later.
  98  */
  99 vproc_transaction_t
 100 vproc_transaction_begin(vproc_t virtual_proc) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_NA);
 101
 102 /*!
 103  * @function vproc_transaction_end
 104  *
 105  * @param       virtual_proc
 106  * This is meant for future API improvements. Pass NULL for now.
 107  *
 108  * @param       handle
 109  * The handle previously created with vproc_transaction_begin().
 110  *
 111  * @abstract
 112  * Call this API after the data has either been flushed or otherwise resolved.
 113  *
 114  * @discussion
 115  * Calling this API with the same handle more than once is undefined.
 116  */
 117 void
 118 vproc_transaction_end(vproc_t virtual_proc, vproc_transaction_t handle) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_NA);
 119
 120 /*!
 121  * @typedef     vproc_standby_t
 122  *
 123  * @abstract
 124  * An opaque handle used to track outstanding standby requests.
 125  */
 126 typedef struct vproc_standby_s *vproc_standby_t;
 127
 128 /*!
 129  * @function vproc_standby_begin
 130  *
 131  * @param       virtual_proc
 132  * This is meant for future API improvements. Pass NULL for now.
 133  *
 134  * @result
 135  * Returns an opaque handle to be passed to vproc_standby_end().
 136  *
 137  * @abstract
 138  * Call this API before registering notifications. For example: timers network
 139  * state change, or when monitoring keyboard/mouse events.
 140  *
 141  * @discussion
 142  * This API is undefined and is currently a no-op.
 143  */
 144 vproc_standby_t
 145 vproc_standby_begin(vproc_t virtual_proc) __OSX_AVAILABLE_STARTING(__MAC_NA, __IPHONE_NA);
 146
 147 /*!
 148  * @function vproc_standby_end
 149  *
 150  * @param       virtual_proc
 151  * This is meant for future API improvements. Pass NULL for now.
 152  *
 153  * @param       handle
 154  * The handle previously created with vproc_standby_begin().
 155  *
 156  * @abstract
 157  * Call this API when deregistering notifications.
 158  *
 159  * @discussion
 160  * Calling this API with the same handle more than once is undefined.
 161  * This API is undefined and is currently a no-op.
 162  */
 163 void
 164 vproc_standby_end(vproc_t virtual_proc, vproc_standby_t handle) __OSX_AVAILABLE_STARTING(__MAC_NA, __IPHONE_NA);
 165
 166 #pragma GCC visibility pop
 167
 168 __END_DECLS
 169
 170 #endif