add doc to event.go

1 files changed, 48 insertions, 0 deletions

diff --git a/event.go b/event.go
index 7ebc643..eea0175 100644
--- a/event.go
+++ b/event.go
@@ -5,11 +5,13 @@ package salticidae
 import "C"
 import "runtime"
 
+// The C pointer type for an EventContext handle
 type CEventContext = *C.eventcontext_t
 type eventContext struct {
     inner CEventContext
     attached map[uintptr]interface{}
 }
+// The handle for an event loop.
 type EventContext = *eventContext
 
 func NewEventContext() EventContext {
@@ -24,15 +26,32 @@ func NewEventContext() EventContext {
 func (self EventContext) attach(ptr rawptr_t, x interface{}) { self.attached[uintptr(ptr)] = x }
 func (self EventContext) detach(ptr rawptr_t) { delete(self.attached, uintptr(ptr)) }
 func (self EventContext) free() { C.eventcontext_free(self.inner) }
+
+// Start the event loop. This is a blocking call that will hand over the
+// control flow to the infinite loop which triggers callbacks upon new events.
+// The function will return when Stop() is called.
 func (self EventContext) Dispatch() { C.eventcontext_dispatch(self.inner) }
+
+// Stop the event loop. This function is typically called in a callback. Notice
+// that all methods of an EventContext should be invoked by the same thread
+// which logically owns the loop. To schedule code executed in the event loop
+// of a particular thread, see ThreadCall.
 func (self EventContext) Stop() { C.eventcontext_stop(self.inner) }
 
+// The C pointer type for a ThreadCall handle.
 type CThreadCall = *C.threadcall_t
 type threadCall struct { inner CThreadCall }
+// The handle for scheduling a function call executed by a particular
+// EventContext event loop.
 type ThreadCall = *threadCall
 
+// The C function pointer type which takes threadcall_handle_t* and void*
+// (passing in the custom user data allocated by C.malloc) as parameters.
 type ThreadCallCallback = C.threadcall_callback_t
 
+// Create a ThreadCall handle attached to the given EventContext. Each
+// invokcation of AsyncCall() will schedule a function call executed in the
+// given EventContext event loop.
 func NewThreadCall(ec EventContext) ThreadCall {
     res := &threadCall{ inner: C.threadcall_new(ec.inner) }
     runtime.SetFinalizer(res, func(self ThreadCall) { self.free() })
@@ -41,19 +60,27 @@ func NewThreadCall(ec EventContext) ThreadCall {
 
 func (self ThreadCall) free() { C.threadcall_free(self.inner) }
 
+// Schedule a function to be executed in the target event loop.
 func (self ThreadCall) AsyncCall(callback ThreadCallCallback, userdata rawptr_t) {
     C.threadcall_async_call(self.inner, callback, userdata)
 }
 
+// The C pointer type for TimerEvent handle.
 type CTimerEvent = *C.timerev_t
 type timerEvent struct {
     inner CTimerEvent
     ec EventContext
 }
+
+// The handle for a timed event.
 type TimerEvent = *timerEvent
 
+// The C function pointer type which takes timerev_t* (the C pointer to
+// TimerEvent) and void* (the unsafe pointer to any userdata) as parameter
 type TimerEventCallback = C.timerev_callback_t
 
+// Create a TimerEvent handle attached to the given EventContext, with a
+// registered callback.
 func NewTimerEvent(_ec EventContext, cb TimerEventCallback, userdata rawptr_t) TimerEvent {
     res := &timerEvent{
         inner: C.timerev_new(_ec.inner, cb, userdata),
@@ -65,26 +92,38 @@ func NewTimerEvent(_ec EventContext, cb TimerEventCallback, userdata rawptr_t) T
 }
 
 func (self TimerEvent) free() { C.timerev_free(self.inner) }
+
+// Change the callback.
 func (self TimerEvent) SetCallback(callback TimerEventCallback, userdata rawptr_t) {
     C.timerev_set_callback(self.inner, callback, userdata)
 }
 
+// Schedule the timer to go off after t_sec seconds.
 func (self TimerEvent) Add(t_sec float64) { C.timerev_add(self.inner, C.double(t_sec)) }
+
+
+// Unschedule the timer if it was scheduled. The timer could still be rescheduled
+// by calling Add() afterwards.
 func (self TimerEvent) Del() {
     self.ec.detach(rawptr_t(self.inner))
     C.timerev_del(self.inner)
 }
 
+// Empty the timer. It will be unscheduled and deallocated and its methods
+// should never be called again.
 func (self TimerEvent) Clear() {
     self.ec.detach(rawptr_t(self.inner))
     C.timerev_clear(self.inner)
 }
 
+// The C pointer type for a SigEvent.
 type CSigEvent = *C.sigev_t
 type sigEvent struct {
     inner CSigEvent
     ec EventContext
 }
+
+// The handle for a UNIX signal event.
 type SigEvent = *sigEvent
 
 type SigEventCallback = C.sigev_callback_t
@@ -94,6 +133,8 @@ var (
     SIGINT = C.SIGINT
 )
 
+// Create a SigEvent handle attached to the given EventContext, with a
+// registered callback.
 func NewSigEvent(_ec EventContext, cb SigEventCallback, userdata rawptr_t) SigEvent {
     res := &sigEvent{
         inner: C.sigev_new(_ec.inner, cb, userdata),
@@ -105,12 +146,19 @@ func NewSigEvent(_ec EventContext, cb SigEventCallback, userdata rawptr_t) SigEv
 }
 
 func (self SigEvent) free() { C.sigev_free(self.inner) }
+
+// Register the handle to listen for UNIX signal sig.
 func (self SigEvent) Add(sig int) { C.sigev_add(self.inner, C.int(sig)) }
+
+
+// Unregister the handle. The handle may be re-registered in the future.
 func (self SigEvent) Del() {
     self.ec.detach(rawptr_t(self.inner))
     C.sigev_del(self.inner)
 }
 
+// Unregister the handle. Any methods of the handle should no longer be used
+// and the handle will be deallocated.
 func (self SigEvent) Clear() {
     self.ec.detach(rawptr_t(self.inner))
     C.sigev_clear(self.inner)