-
Notifications
You must be signed in to change notification settings - Fork 0
/
event_active.3
95 lines (95 loc) · 2.72 KB
/
event_active.3
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
.\" $OpenBSD$
.\" Copyright (c) 2023 Ted Bullock <[email protected]>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt EVENT_ACTIVE 3
.Os
.Sh NAME
.Nm event_active
.Nd manually trigger an event
.Sh SYNOPSIS
.In event.h
.Ft void
.Fn event_active "struct event *ev" "int res" "short ncalls"
.Sh DESCRIPTION
Programs may occasionally need to manually trigger events with user-defined
behavior.
This is accomplished with the
.Fn event_active
function, which signals an event loop to process the event and invoke the
event callback
.Fa ncalls
number of times in a row.
The arguments are as follows:
.Bl -tag -width "ncalls:"
.It Fa ev :
A pointer to the
.Vt event
to be triggered; if
.Fa ev
is
.Dv NULL
the behavior is undefined.
.It Fa res :
A bitmask specifying which event flags to activate.
.Dv EV_TIMEOUT ,
.Dv EV_READ ,
.Dv EV_WRITE ,
.Dv EV_SIGNAL ,
and
.Dv EV_PERSIST
are valid flags consistent with event library semantics.
Other flags may produce undefined behavior or be ignored by library functions.
Refer to
.Xr event_set 3
for a detailed explanation of event flags.
.It Fa ncalls :
The number of times the callback function should be executed.
The behavior is undefined if
.Fa ncalls
is negative or zero.
.El
.Pp
This function updates the event flags on activated events and makes
no other changes.
.Pp
.Fn event_active
causes a segmentation fault if executed without previously invoking at least
.Xr event_set 3 .
.Xr event_base_set 3
is
.Em also
required for programs initialized with
.Xr event_base_new 3 .
.Pp
The function preserves an events queue number configured with
.Xr event_priority_set 3 .
The event is processed consistent with the priority promise of that queue.
.Sh SEE ALSO
.Xr event_base_new 3 ,
.Xr event_base_loop 3 ,
.Xr event_priority_set 3 ,
.Xr event_set 3
.Sh HISTORY
.Fn event_active
first appeared in libevent-0.4 and has been available since
.Ox 3.2 .
.Sh AUTHORS
The event library and this function was written by
.An -nosplit
.An Niels Provos .
.Pp
This manual page was written by
.An Ted Bullock Aq Mt [email protected] .