Libevent R4: Working with events

Overview

원문은 이곳<ref>http://www.wangafu.net/~nickm/libevent-book/Ref4_event.html</ref>에서 확인할 수 있다.

Libevent의 기본 실행 단위는 event(이벤트)이다. 모든 이벤트는 상태를 가지게 되는데 이는 다음과 같다.

파일 디스크립터의 read/write 준비 완료
파일 디스크립터의 read/write 준비 중(Egde-triggered IO Only)
timout 만료
signal 발생
사용자-정의 trigger

이벤트들은 비슷한 주기를 가지게 되는데, 한번 이벤트를 생성하게 되면 initialized 상태가 된다. 이후 event_base 에 등록하게 되면 pending 상태가 된다. 이벤트가 pending 상태에서 특정 조건을 만족하여 trigger(readable/writable, timeout expire) 되게 되면, active 상태가 되면서 등록된 callback 함수가 실행된다. 만약 이벤트가 persistent 로 설정되었다면, 다시 pending 상태로 돌아간다. 만약 persistent 가 아니라면, pending으로 돌아가지 않는다. 이벤트 delete 를 함으로써 pending 상태에서 non-pending 상태로 바꿀 수 있으며, add 를 이용해서 non-pending 에서 pending으로 변경할 수도 있다.

Constructing event objects

새로운 이벤트를 생성하기 위해서는 event_new() 인터페이스를 사용하면 된다.

Interface

define EV_TIMEOUT 0x01
define EV_READ 0x02
define EV_WRITE 0x04
define EV_SIGNAL 0x08
define EV_PERSIST 0x10
define EV_ET 0x20

typedef void (*event_callback_fn)(evutil_socket_t, short, void *);

struct event *event_new(struct event_base *base,

   evutil_socket_t fd,
   short what, 
   event_callback_fn cb,
   void *arg);

void event_free(struct event *event); </source>

event_new() 함수는 같이 넘겨지는 인자 *base 에서 동작하는 이벤트를 생성한다. 그리고 what 인자는 flag 셋인데, 사용가능한 flag 가 위쪽에 나와있다. 만약 fd 가 양수 값으로 설정됐다면, read/write 하고자 하는 파일 디스크립터 값으로 간주된다. 이벤트가 active 되면, 이벤트는 여기서 등록된 cb 함수를 다음의 인자 값과 함께 실행시킨다(fd : 파일 디스크립터, arg: 이벤트 생성시 넘겨준 arg 값)

오류 발생시, event_new() 는 NULL 을 리턴한다.

모든 이벤트는 생성 직후 initialized 상태 혹은 non-pending 상태가 된다. pedning 상태로 만들기 위해서는 event_add() 를 호출해야 한다.(아래에서 설명함)

이벤트를 삭제(메모리 해제)하고 한다면 event_free() 를 사용해야 하며, 해당 이벤트가 pending/active 상태 중에서도 사용 가능하다.(해당 이벤트가 non-pending/inactive 상태일 때 삭제된다)

Example

include <event2/event.h>

void cb_func(evutil_socket_t fd, short what, void *arg) {

   const char *data = arg;
   printf("Got an event on socket %d:%s%s%s%s [%s]",
       (int) fd,
       (what & EV_TIMEOUT)?    " timeout" : "",
       (what & EV_READ)?       " read" : "",
       (what & EV_WRITE)?      " write" : "",
       (what & EV_SIGNAL)?     " signal" : "",
       data);

}

void main_loop(evutil_socket_t fd1, evutil_socket_t fd2) {

   struct event *ev1, *ev2;
   struct timeval five_seconds = {5, 0};
   struct event_base *base = event_base_new();
   
   /* The caller has already set up fd1, fd2 somehow, and make them
    * nonblocking. */
    
   ev1 = event_new(base, fd1, EV_TIMEOUT|EV_READ|EV_PERSIST, cb_func, (char*)"Reading event");
   ev2 = event_new(base, fd2, EV_WRITE|EV_PERSIST, cb_func, (char*)"Writing event");
   
   event_add(ev1, &five_seconds);
   event_add(ev2, NULL);
   event_base_dispatch(base);

} </source>

The event flags

EV_TIMEOUT

같이 설정한 시간뒤에 active 된다.

EV_READ

등록한 파일 디스크립터가 Read 가능한 상태일 때 active 된다.

EV_WRITE

등록한 파일 디스크립터가 Write 가능한 상태일 때 active 된다.

EV_SIGNAL

등록한 시그널이 감지될 때 active 된다.

EV_PERSIST

해당 이벤트는 "영구적"임을 나타낸다.

EV_ET

event_base 의 백엔드가 Edge-trigger 를 지원할 때, 해당 이벤트가 Edge-triggered 를 사용한다는 것을 나타낸다. EV_READ/EV_WRITE 의 Edge-trigger 버전이다.

About Event Persistance

기본적으로 이벤트가 pending 상태에서 active 상태가 되면, 등록된 callback 함수가 실행된 직후, non-pending 상태가 된다. 따라서 만약 해당 이벤트를 다시금 pending 상태로 만들고 싶다면, 콜백 함수 내에서 event_add() 통해 다시금 이벤트를 등록시켜주어야 한다.

하지만 만약 EV_PERSIST 플래그가 세팅되어 있다면, 이벤트는 영구적이 된다. 무슨 말이냐면, 이벤트가 active 상태가 되어 콜백을 실행시킨 이후에 다시 pending 상태로 돌아온다는 뜻이다. 만약 non-pending 상태로 만들고 싶다면, event_del() 를 사용하면 된다.

timeout과 persistent 옵션을 같이 사용하게 되면, timout 와 trigger 를 공유하는 형태가 된다. 예를 들어 EV_READ|EV_PERSIST 와 timeout 5초를 함께 설정하게 되면 다음과 같이 된다.

소켓이 read 가능하면 active된다.
마지막으로 active 된 지 매 5 초 후마다 active 된다.

Creating an event as its own callback argument

때때로, 콜백 함수 자신을 인자값으로 처리해야 하는 경우가 있을 수 있다. 하지만 이벤트 자체를 그냥 포인터로 넘겨줄 수는 없다. 왜냐하면 아직 생성되지 않았기 때문이다. 실제로 이벤트가 active 되고 실행하는 순간 callback 메모리가 할당되기 때문이다. 따라서 이를 위해서는 별도의 event_self_cbarg() 함수를 사용해야 한다.

Interface

<source lang=c> void *event_self_arg(); </source>

event_self_cbarg()는 콜백 함수를 가리키는 "매직 포인터"를 리턴해준다.

Example

include <event2/event.h>

static int n_calls = 0;

void cb_func(evutil_socket_t fd, short what, void *arg) {

   struct event *me = arg;
   
   printf("cb_func called %d times so far.\n", ++n_calls);
   
   if(n_calls > 100)
   {
       event_del(me);
   }

}

void run(struct event_base *base) {

   struct timeval one_sec = {1, 0};
   struct event *ev;
   /* We're going to set up a repeating timer to get called called 100
    * times. */
   ev = event_new(base, -1, EV_PERSIST, cb_func, event_self_cbarg());
   event_add(ev, &one_sec);
   event_base_dispatch(base);

} </source> event_new(), evtimer_new(), evsignal_new(), event_assign(), evtimer_assign, evsignal_assign() 등과 함께 사용할 수 있다.

Timeout-only events

evtimer_ 로 시작하는 매크로 들이 있다. event_ 로 시작하는 함수와 timer 관련 옵션을 함께 설정할때 사용가능한데, 이를 사용하면 번거로운 작업을 줄일 수 있다.

Interface

define evtimer_new(base, callback, arg) \

   event_new(base), -1, 0, (callback), (arg))

define evtimer_add(ev, tv) \

   event_add((ev), (tv))

define evtimer_Del(ev) \

   event_del(ev)

define evtimer_pending(ev, tv_out) \

   event_pending((ev), EV_TIMEOUT, (tv_out))

</source>

Constructing signal events

Libevent는 POSIX 시그널도 감지가 가능하다.

Interface

define evsignal_new(base, signum, cb, arg) \

   event_new(base, signum, EV_SIGNAL|EV_PERSIST, cb, arg)

</source> event_new 사용법과 같은데, 파일 디스크립터 대신 시그널 번호만 넘겨주는 것이 다르다.

Example

<source lang=c> struct event *hup_event; struct event_base *base = event_base_new();

/* call sighup_function on a HUP signal */ hup_event = evsignal_new(base, SIGHUP, sighup_function, NULL); </source> 등록한 시그널 콜백은 시그널이 발생될때 이벤트 루프에서 호출된다. 따라서 시그널 콜백 사용시, POSIX 시그널 핸들러에 아무처리를 하지않도록 따로 설정해놓는 것이 안전하다.

signal event 등록은 위한 매크로 역시 존재한다.

Interface

define evsignal_add(ev, tv) \

   event_add((ev), (tv))

define evsignal_del(ev) \

   event_del(ev)

define evsignal_pending(ev, what, tv_out) \

   event_pending((ev), (what), (tv_out))

</source>

Caveats when working with signals

Libevent 에서 시그널을 등록해서 사용할 때 주의해야할 점이 있다. 프로세스당 오직 하나의 event_base 에서만 시그널을 수신할 수 있다는 것이다. 만약 하나의 프로세스에서 여러개의 event_base 를 생성하고 각각의 event_base 마다 시그널을 등록했을 경우, 오직 하나의 event_base 에서만 시그널을 수신하게 된다는 것이다. 시그널의 번호가 모두 달라도 안된다.

단, kqueue 에서는 제약이 없다.

Setting up events without heap-allocation

성능, 혹은 다른 이유로 힙영역 이외의 다른 곳에 이벤트 메모리를 관리할 수 있다. 이 기능을 사용하게 되면 다음의 문제들을 관리할 수 있다.

작은 양의 메모리를 heap 영역에 할당하게 되면 오버헤드가 발생한다.
struct event pointer 를 역 조회하게되면 time overhead 가 발생한다.
만약 이벤트가 캐시에 없는 경우, 이를 위한 time-overhead 가 발생할 수 있다.

이를 위해서는 event_assign() 을 사용하면 된다. 하지만 이를 사용하게 되면 다른 버전의 Libevent 와의 바이너리 호환성을 깨트릴 수 있다. 왜냐하면 이벤트 구조체의 사이즈가 달라질 수 있기 때문이다.

위에 나열한 문제들은 굉장히 작은 문제들이다. 그리고 거의 대부분의 어플리케이션에서는 문제되지 않는다. 이벤트 메모리를 다른 곳에 관리함으로써 생기는 문제점들에 대해 정확히 알고있지 않은 한, event_new() 를 사용하길 바란다. event_assign()을 사용하게 되면 다른 버전의 Libevent(만약 이벤트 구조체 크기가 달라졌다면)와 연동했을 경우, 에러를 찾기 힘들어진다.

Interface

<source lang=c> int event_assign(struct event *event,

   struct event_base *base,
   evutil_socket_t fd, 
   short what,
   void (*callback)(evutil_socket_t, short, void *), 
   void *arg);

</source> event 인자값을 제외한, 모든 인자값은 event_new() 에서 사용하는 것과 같다. 성공시 0, 실패시 -1을 리턴한다.

Example

include <event2/event.h>

/* Watch out! Including event_struct.h means that your code will not

* be binary-compatible with future versions of Libevent. */

include <event2/event_struct.h>
include <stdlib.h>

struct event_pair {

   evutil_socket_t fd;
   struct event read_event;
   struct event write_event;

}; void readcb(evutil_socket_t, short, void *); void writecb(evutil_socket_t, short, void *); struct event_pair *event_pair_new(struct event_base *base, evutil_socket_t fd) {

   struct event_pair *p = malloc(sizeof(struct event_pair));
   if(!p) return NULL;
   p->fd = fd;
   event_assign(&p->read_event, base, fd, EV_READ|EV_PERSIST, readcb, p);
   event_assign(&p->write_event, base, fd, EV_WRITE|EV_PERSIST, writecb, p);
   return p;

} </source>

Warning

절대로 pending 중인 이벤트에 대해 event_assign() 를 사용하면 안되다. 만약 그런 일을 하게되면 정말로 오류가 발생해도 원인을 찾을 수 없게 된다. 만약 이미 Initialized 됐고, pending 상태의 이벤트라면, event_del() 을 먼저 사용하고, event_assign()을 사용해야 한다.

assign 과 관련된 매크로 함수들 역시 존재한다.

Interface

define evtimer_assign(event, base, callback, arg) \

   event_assign(event, base, -1, 0, callback, arg)

define evsignal_assign(event, base, signum, callback, arg) \

   event_assign(event, base, signum, EV_SIGNAL|EV_PERSIST, callback arg)

</source>

event_assign() 을 사용하면서도 추후의 Libevent 라이브러리와 바이너리 호환성을 유지해야 한다면, 사용중인 라이브러리의 struct event 크기를 확인할 수 있다.

Interface

<source lang=c> size_t event_get_struct_event_size(void); </source>

이 함수는 현재 사용중인 이벤트 구조체의 바이트 크기를 리턴한다. This function returns the number of bytes you need to set aside for a struct event. As before, you should only be using this function if you know that heap-allocation is actually a significant problem in your program, since it can make your code much harder to read and write.

Note that event_get_struct_event_size() may in the future give you a value smaller than sizeof(struct event). If this happens, it means that any extra bytes at the end of struct event are only padding bytes reserved for use by a future version of Libevent.

Here’s the same example as above, but instead of relying on the size of struct event from event_struct.h, we use event_get_struct_size() to use the correct size at runtime.

References

Libevent R4: Working with events

Contents

Overview

Constructing event objects

The event flags

About Event Persistance

Creating an event as its own callback argument

Timeout-only events

Constructing signal events

Setting up events without heap-allocation

References

Navigation menu

Libevent R4: Working with events

Overview

Constructing event objects

The event flags

About Event Persistance

Creating an event as its own callback argument

Timeout-only events

Constructing signal events

Setting up events without heap-allocation

References

Navigation menu

Search