libpeak-0.1.2/peak/signal.h

/* PEAK Library
 *
 * Copyright (c) 2003, 2004
 *      Stephane Thiell <mbuna@bugged.org>. All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 * 
 * $Id: signal.h,v 1.4 2004/01/08 19:03:54 mbuna Exp $
 */
#ifndef INCLUDED_PEAK_SIGNAL_H_
#define INCLUDED_PEAK_SIGNAL_H_

#include <peak/task.h>

/*!
 * @defgroup signal Signal notifications
 * The PEAK Library wraps signal interruptions to provide safe signal
 * notifications (via a callback). Now you can consider handling signals
 * like any other events (stream, timer, etc.). The API is very simple here,
 * when you want to handle a signal (defined by a number), use
 * peak_signal_create() and specify a pointer to a callback function. Then,
 * schedule a task for signal notifications using peak_signal_schedule().
 * For convenience, especially for use with SIGPIPE, a peak_signal_ignore()
 * method is provided to ignore a specified signal.
 */

/*!
 * @ingroup signal
 * @brief Opaque type for the signal object.
 */
typedef struct __peak_signal * peak_signal;

/*!
 * @ingroup signal
 * @brief Signal notification callback type.
 */
typedef void (*peak_signal_event_callback)(peak_signal i, int value,
                                           void *context);

#if defined(__cplusplus)
extern "C" {
#endif

/*!
 * @ingroup signal
 * @brief Create a new signal notification object.
 * 
 * @param signum  The signal number to handle.
 * @param cb      A pointer to your notification callback function that handles
 *                signal events that may occur once scheduled.
 * @param context An extra application-defined pointer that will be passed
 *                to your signal event callback function (it's not used by the
 *                library).
 *
 * @return        A newly allocated peak_signal reference or NULL if an error
 *                was encountered.
 */
extern peak_signal peak_signal_create(int signum,
                                      peak_signal_event_callback cb,
                                      void *context);

/*!
 * @ingroup signal
 * @brief Ignore a signal.
 * 
 * Note that some signals can't be handled nor ignored, like SIGKILL.
 * 
 * @param signum  The signal number to ignore.
 *
 * @retval 0      The operation was successful.
 * @retval -1     The signal can't be ignored, error might be set to indicate
 *                the error (just like sigaction(2) does).
 */
extern int peak_signal_ignore(int signum);

/*!
 * @ingroup signal
 * @brief Schedule a task for signal event notification.
 * 
 * This will enable you to receive signal notifications (using the provided
 * callback in peak_signal_create()) within the specified task. If the task
 * has several threads, one of its thread calls the callback.
 * 
 * @param  i      The signal object.
 * @param task    The task to schedule (usually peak_task_self()).
 */
extern void peak_signal_schedule(peak_signal i, peak_task task);

/*!
 * @ingroup signal
 * @brief Unschedule a task for signal event notification.
 * 
 * This will disable notifications for the specified signal object.
 * 
 * @param  i      The signal object.
 * @param task    The task to unschedule (usually peak_task_self()).
 */
extern void peak_signal_unschedule(peak_signal i, peak_task task);

#if defined(__cplusplus)
}
#endif

#endif /* INCLUDED_PEAK_SIGNAL_H_ */
Revision:	3251
Committed:	Wed Apr 2 16:58:30 2014 UTC (11 years, 4 months ago) by michael
Content type:	text/x-chdr
File size:	4589 byte(s)
Log Message:	- Imported libpeak-0.1.2
#	Content
1	/* PEAK Library
2	*
3	* Copyright (c) 2003, 2004
4	* Stephane Thiell <mbuna@bugged.org>. All rights reserved.
5	*
6	* Redistribution and use in source and binary forms, with or without
7	* modification, are permitted provided that the following conditions
8	* are met:
9	*
10	* 1. Redistributions of source code must retain the above copyright
11	* notice, this list of conditions and the following disclaimer.
12	*
13	* 2. Redistributions in binary form must reproduce the above copyright
14	* notice, this list of conditions and the following disclaimer in the
15	* documentation and/or other materials provided with the distribution.
16	*
17	* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
18	* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
19	* TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
20	* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
21	* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
22	* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
23	* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
24	* OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
25	* WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
26	* OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
27	* ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28	*
29	* $Id: signal.h,v 1.4 2004/01/08 19:03:54 mbuna Exp $
30	*/
31	#ifndef INCLUDED_PEAK_SIGNAL_H_
32	#define INCLUDED_PEAK_SIGNAL_H_
33
34	#include <peak/task.h>
35
36	/*!
37	* @defgroup signal Signal notifications
38	* The PEAK Library wraps signal interruptions to provide safe signal
39	* notifications (via a callback). Now you can consider handling signals
40	* like any other events (stream, timer, etc.). The API is very simple here,
41	* when you want to handle a signal (defined by a number), use
42	* peak_signal_create() and specify a pointer to a callback function. Then,
43	* schedule a task for signal notifications using peak_signal_schedule().
44	* For convenience, especially for use with SIGPIPE, a peak_signal_ignore()
45	* method is provided to ignore a specified signal.
46	*/
47
48	/*!
49	* @ingroup signal
50	* @brief Opaque type for the signal object.
51	*/
52	typedef struct __peak_signal * peak_signal;
53
54	/*!
55	* @ingroup signal
56	* @brief Signal notification callback type.
57	*/
58	typedef void (*peak_signal_event_callback)(peak_signal i, int value,
59	void *context);
60
61	#if defined(__cplusplus)
62	extern "C" {
63	#endif
64
65	/*!
66	* @ingroup signal
67	* @brief Create a new signal notification object.
68	*
69	* @param signum The signal number to handle.
70	* @param cb A pointer to your notification callback function that handles
71	* signal events that may occur once scheduled.
72	* @param context An extra application-defined pointer that will be passed
73	* to your signal event callback function (it's not used by the
74	* library).
75	*
76	* @return A newly allocated peak_signal reference or NULL if an error
77	* was encountered.
78	*/
79	extern peak_signal peak_signal_create(int signum,
80	peak_signal_event_callback cb,
81	void *context);
82
83	/*!
84	* @ingroup signal
85	* @brief Ignore a signal.
86	*
87	* Note that some signals can't be handled nor ignored, like SIGKILL.
88	*
89	* @param signum The signal number to ignore.
90	*
91	* @retval 0 The operation was successful.
92	* @retval -1 The signal can't be ignored, error might be set to indicate
93	* the error (just like sigaction(2) does).
94	*/
95	extern int peak_signal_ignore(int signum);
96
97	/*!
98	* @ingroup signal
99	* @brief Schedule a task for signal event notification.
100	*
101	* This will enable you to receive signal notifications (using the provided
102	* callback in peak_signal_create()) within the specified task. If the task
103	* has several threads, one of its thread calls the callback.
104	*
105	* @param i The signal object.
106	* @param task The task to schedule (usually peak_task_self()).
107	*/
108	extern void peak_signal_schedule(peak_signal i, peak_task task);
109
110	/*!
111	* @ingroup signal
112	* @brief Unschedule a task for signal event notification.
113	*
114	* This will disable notifications for the specified signal object.
115	*
116	* @param i The signal object.
117	* @param task The task to unschedule (usually peak_task_self()).
118	*/
119	extern void peak_signal_unschedule(peak_signal i, peak_task task);
120
121	#if defined(__cplusplus)
122	}
123	#endif
124
125	#endif /* INCLUDED_PEAK_SIGNAL_H_ */