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
36typedef void * vproc_err_t;
37
38typedef struct vproc_s * vproc_t;
39typedef void * vprocmgr_t;
40
41const 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 */
86typedef 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 */
100vproc_transaction_t
101vproc_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 */
118void
119vproc_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 */
127typedef 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 */
145vproc_standby_t
146vproc_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 */
164void
165vproc_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__ */
172