← Back to branch summary

~ubuntu-branches/ubuntu/saucy/syslog-ng/saucy

« back to all changes in this revision

Viewing changes to lib/ivykis/modules/man3/iv_event_raw.3

  • Committer: Package Import Robot
  • Author(s): Serge Hallyn
  • Date: 2011-11-15 08:48:02 UTC
  • mfrom: (26.1.2 sid)
  • Revision ID: package-import@ubuntu.com-20111115084802-n0jegdnjlxk0m26s
Tags: 3.3.1.dfsg-1ubuntu1
* debian/control: remove libsystemd-daemon-dev build-depends
* debian/rules: remove --with-systemdsystemunitdir from
  override_dh_auto_configure.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/ivykis/modules/man3/iv_event_raw.3
 
1
.\" This man page is Copyright (C) 2010 Lennert Buytenhek.
 
2
.\" Permission is granted to distribute possibly modified copies
 
3
.\" of this page provided the header is included verbatim,
 
4
.\" and in case of nontrivial modification author and date
 
5
.\" of the modification is added to the header.
 
6
.TH iv_event_raw 3 2010-09-02 "ivykis" "ivykis programmer's manual"
 
7
.SH NAME
 
8
IV_EVENT_RAW_INIT, iv_event_raw_register, iv_event_raw_unregister, iv_event_raw_post \- manage ivykis objects for event notification
 
9
.SH SYNOPSIS
 
10
.B #include <iv_event_raw.h>
 
11
.sp
 
12
.nf
 
13
struct iv_event_raw {
 
14
        void            *cookie;
 
15
        void            (*handler)(void *);
 
16
};
 
17
.fi
 
18
.sp
 
19
.BI "void IV_EVENT_RAW_INIT(struct iv_event_raw *" this ");"
 
20
.br
 
21
.BI "int iv_event_raw_register(struct iv_event_raw *" this ");"
 
22
.br
 
23
.BI "void iv_event_raw_unregister(struct iv_event_raw *" this ");"
 
24
.br
 
25
.BI "void iv_event_raw_post(struct iv_event_raw *" this ");"
 
26
.br
 
27
.SH DESCRIPTION
 
28
.B iv_event_raw
 
29
provides a way for delivering events to
 
30
.BR ivykis (3)
 
31
recipients across thread and process boundaries.
 
32
.PP
 
33
The intended event recipient calls
 
34
.B IV_EVENT_RAW_INIT
 
35
on a
 
36
.B struct iv_event_raw
 
37
object, fills in
 
38
.B ->cookie
 
39
and
 
40
.B ->handler,
 
41
and then calls
 
42
.B iv_event_raw_register
 
43
on the object.
 
44
.PP
 
45
To generate an event, call
 
46
.B iv_event_raw_post
 
47
on the previously initialized
 
48
.B struct iv_event_raw
 
49
object.  This will cause the callback specified by
 
50
.B ->handler
 
51
to be called in the thread that the
 
52
.B struct iv_event_raw
 
53
object was registered in, with
 
54
.B ->cookie
 
55
as its sole argument.
 
56
.PP
 
57
To deinitialize a
 
58
.B struct iv_event_raw
 
59
object, call
 
60
.B iv_event_raw_unregister
 
61
from the same thread that
 
62
.B iv_event_raw_register
 
63
was called from on that object.
 
64
.PP
 
65
It is permitted to unregister a
 
66
.B struct iv_event_raw
 
67
object from any ivykis callback function in the thread it was
 
68
registered in, including from a callback function triggered by this
 
69
object, and it is permitted to free the memory corresponding to an
 
70
unregistered object from its own callback function.
 
71
.PP
 
72
.B iv_event_raw_post
 
73
can be called from the same thread that
 
74
.B iv_event_raw_register
 
75
was called from, from a different thread in the same process, or even
 
76
from a different process, and can safely be called from signal handlers.
 
77
.PP
 
78
If posting an event only ever needs to be done from within the same
 
79
process, see
 
80
.BR iv_event (3)
 
81
for a lighter-weight alternative to
 
82
.B iv_event_raw.
 
83
.PP
 
84
Internally,
 
85
.B iv_event_raw
 
86
is implemented by registering a file descriptor (a struct
 
87
.BR iv_fd (3))
 
88
with the recipient thread's ivykis event loop, and by causing that
 
89
file descriptor to become readable upon a call to
 
90
.B iv_event_raw_post.
 
91
.PP
 
92
If
 
93
.BR eventfd (2)
 
94
is available, it will be used to procure the abovementioned file
 
95
descriptor.  If not,
 
96
.B iv_event_raw
 
97
will fall back to
 
98
.BR pipe (2)
 
99
as the source of its file descriptors.
 
100
.BR eventfd (2)
 
101
is preferred as it requires only one file descriptor table entry
 
102
(while
 
103
.BR pipe (2)
 
104
requires two), and has much less kernel overhead than
 
105
.BR pipe (2)
 
106
has.
 
107
.SH "SEE ALSO"
 
108
.BR ivykis (3),
 
109
.BR iv_event (3),
 
110
.BR eventfd (2),
 
111
.BR pipe (2)