module Libvirt

Unlike most of the other functions in the ruby-libvirt bindings, this one does not directly correspond to a libvirt API function. Instead, this module method (and event_invoke_timeout_callback) are meant to be called when there is an event of interest to libvirt on one of the file descriptors that libvirt uses. The application is notified of the file descriptors that libvirt uses via the callbacks from Libvirt::event_register_impl. When there is an event of interest, the application must call event_invoke_timeout_callback to ensure proper operation.

Libvirt::event_invoke_handle_callback takes 4 arguments:

handle - an application specific handle ID. This can be any integer, but must be unique from all other libvirt handles in the application.

fd - the file descriptor of interest. This was given to the application as a callback to add_handle of Libvirt::event_register_impl

events - the events that have occured on the fd. Note that the events are libvirt specific, and are some combination of Libvirt::EVENT_HANDLE_READABLE, Libvirt::EVENT_HANDLE_WRITABLE, Libvirt::EVENT_HANDLE_ERROR, Libvirt::EVENT_HANDLE_HANGUP. To notify libvirt of more than one event at a time, these values should be logically OR’ed together.

opaque - the opaque data passed from libvirt during the Libvirt::event_register_impl add_handle callback. To ensure proper operation this data must be passed through to event_invoke_handle_callback without modification.

static VALUE libvirt_event_invoke_handle_callback(VALUE RUBY_LIBVIRT_UNUSED(m),
                                                  VALUE handle, VALUE fd,
                                                  VALUE events, VALUE opaque)
{
    virEventHandleCallback cb;
    void *op;
    VALUE libvirt_cb, libvirt_opaque;

    Check_Type(opaque, T_HASH);

    libvirt_cb = rb_hash_aref(opaque, rb_str_new2("libvirt_cb"));

    /* This is equivalent to Data_Get_Struct; I reproduce it here because
     * I don't want the additional type-cast that Data_Get_Struct does
     */
    Check_Type(libvirt_cb, T_DATA);
    cb = DATA_PTR(libvirt_cb);

    if (cb) {
        libvirt_opaque = rb_hash_aref(opaque, rb_str_new2("opaque"));
        Data_Get_Struct(libvirt_opaque, void *, op);
        cb(NUM2INT(handle), NUM2INT(fd), NUM2INT(events), op);
    }

    return Qnil;
}

Unlike most of the other functions in the ruby-libvirt bindings, this one does not directly correspond to a libvirt API function. Instead, this module method (and event_invoke_handle_callback) are meant to be called when there is a timeout of interest to libvirt. The application is notified of the timers that libvirt uses via the callbacks from Libvirt::event_register_impl. When a timeout expires, the application must call event_invoke_timeout_callback to ensure proper operation.

Libvirt::event_invoke_timeout_callback takes 2 arguments:

handle - an application specific timer ID. This can be any integer, but must be unique from all other libvirt timers in the application.

opaque - the opaque data passed from libvirt during the Libvirt::event_register_impl add_handle callback. To ensure proper operation this data must be passed through to event_invoke_handle_callback without modification.

static VALUE libvirt_event_invoke_timeout_callback(VALUE RUBY_LIBVIRT_UNUSED(m),
                                                   VALUE timer, VALUE opaque)
{
    virEventTimeoutCallback cb;
    void *op;
    VALUE libvirt_cb, libvirt_opaque;

    Check_Type(opaque, T_HASH);

    libvirt_cb = rb_hash_aref(opaque, rb_str_new2("libvirt_cb"));

    /* This is equivalent to Data_Get_Struct; I reproduce it here because
     * I don't want the additional type-cast that Data_Get_Struct does
     */
    Check_Type(libvirt_cb, T_DATA);
    cb = DATA_PTR(libvirt_cb);

    if (cb) {
        libvirt_opaque = rb_hash_aref(opaque, rb_str_new2("opaque"));
        Data_Get_Struct(libvirt_opaque, void *, op);
        cb(NUM2INT(timer), op);
    }

    return Qnil;
}