what's the difference between pending and active event in Libevent? - sockets

Question

I'm learning how to use Libevent.While I can't understand the difference between pending and active.In my opinion,when a event is added to a event_base and the event hasn't happened, then it's in pending state,while the event which is waited by the caller is happened,then in the active state,is that right?Hoever,when I read the description of event_pending,see the code blew,it says when the event is pending,it's bad to change the inner state of it,i think the word "pending" here is misunderstand,it should be "event_active"....Am i wrong ?
#include <event2/event.h>
#include <stdio.h>
/* Change the callback and callback_arg of 'ev', which must not be
* pending. */
int replace_callback(struct event *ev, event_callback_fn new_callback,
void *new_callback_arg)
{
struct event_base *base;
evutil_socket_t fd;
short events;
int pending;
pending = event_pending(ev, EV_READ|EV_WRITE|EV_SIGNAL|EV_TIMEOUT,
NULL);
if (pending) {
/* We want to catch this here so that we do not re-assign a
* pending event. That would be very very bad. */
fprintf(stderr,
"Error! replace_callback called on a pending event!\n");
return -1;
}
event_get_assignment(ev, &base, &fd, &events,
NULL /* ignore old callback */ ,
NULL /* ignore old callback argument */);
event_assign(ev, base, fd, events, new_callback, new_callback_arg);
return 0;
}

Answer 1

pending event means that some action triggered and execution of event callback is queued in event_base.
active event means that event callback is currently executed current thread or some other(do not forget that you can manipulate events from other thread, that is not running event loop)
Reassigning a pending event is not thread safe operation, you can see it in event.c.
I think if you writing single-threaded application it's safe to reassigning event at any time.

Answer 2

libevent book quote (http://www.wangafu.net/~nickm/libevent-book/Ref4_event.html):
Once you call a Libevent function to set up an event and associate it with an event base, it becomes initialized. At this point, you can add, which makes it pending in the base. When the event is pending, if the conditions that would trigger an event occur (e.g., its file descriptor changes state or its timeout expires), the event becomes active, and its (user-provided) callback function is run.
So "pending" in libevent terms means "just added in reactor". No action triggering need to get pending event. I've checked this behavior with simple program:
#include <stdio.h>
#include <unistd.h>
#include <assert.h>
#include <event.h>
void read_cb( int sock, short which, void *arg )
{
printf( "read_cb() called\n" );
fflush( stdout );
// while our callback is running event is active
}
int main()
{
struct event_base *base = event_base_new();
int fd[ 2 ];
assert( pipe( fd ) == 0 );
struct event ev;
event_set( & ev, fd[ 0 ], EV_READ | EV_PERSIST, read_cb, NULL );
event_base_set( base, & ev );
assert( event_add( & ev, NULL ) != -1 );
// it's pending now, just after adding
printf( "event_pending( ... ) == %d\n", event_pending( & ev, EV_READ, NULL ) );
fflush( stdout );
event_base_loop( base, EVLOOP_ONCE );
return 0;
}
Output:
event_pending( ... ) == 2