Merge branch 'python2' of http://git.sipsolutions.net/trace-cmd into trace-cmd

11 files changed, 592 insertions, 79 deletions

diff --git a/Documentation/README.PythonPlugin b/Documentation/README.PythonPlugin
new file mode 100644
index 0000000..3de0564
--- /dev/null
+++ b/Documentation/README.PythonPlugin
@@ -0,0 +1,127 @@
+ PYTHON PLUGIN DOCUMENTATION
+=============================
+
+With the python plugin (make python-plugin) you can now
+write plugins in python. The API exported by the python
+plugin itself (written in C) allows you to access most
+information about a record from python.
+
+To write a python plugin, put a new .py file into a new
+~/.trace-cmd/python/ directory.
+
+The most basic python plugin is this:
+
+--- %< ---
+def register(pevent):
+    pass
+--- >% ---
+
+which obviously does nothing at all.
+
+To register a callback, use the pevent.register_event_handler
+function:
+
+--- %< ---
+import tracecmd
+
+def my_event_handler(trace_seq, event):
+    pass
+
+def register(pevent):
+    pevent.register_event_handler("subsys", "event_name",
+                                  my_event_handler)
+--- >% ---
+
+
+There are four object types that you get, described below.
+
+ tracecmd.PEvent
+-----------------
+
+This is the class of the 'pevent' object above,
+you get one of those via your register callback.
+It has one method and one property:
+ * register_event_handler() - example above, to register
+                              an event handler function
+ * file_endian              - either '<' or '>' indicating
+                              which endianness the file has,
+                              to be used with struct.unpack()
+
+ tracecmd.TraceSeq
+-------------------
+
+This is the class of the 'trace_seq' parameter to your callback
+function. It has only one method, puts(), to put data into the
+buffer. Formatting must be done in python.
+
+ tracecmd.Event
+----------------------
+
+This is the class of the 'event' parameter to your callback
+function. Note that it doesn't just contain the format, but
+also the event data. As such, you can do much with this, and
+this is what you'll usually use. Each instance of this allows
+access to record items via the dict protocol, and you can get
+the items via its keys() methods. So for example, your
+callback could be
+
+--- %< ---
+def my_callback(trace_seq, event):
+    for fieldname in event.keys():
+        field = event[fieldname]
+--- >% ---
+
+Each field returned from the dict protocol is an instance of
+the next (and last) class:
+
+ tracecmd.Field
+----------------------
+
+This is an instance of a field, including its data. It affords
+numerous use cases and is what you'll be using most.
+
+ * If this is an integer field, i.e. 1, 2, 4 or 8 bytes long,
+   you can convert it to the number contained, according to
+   the file's endianness, by simply casting it to a long:
+
+     field = event['myint']
+     value = long(field)
+
+ * You can access the field's data, as field.data, and if the
+   data is really a "__data_loc" type that will be resolved
+   automatically. (If you don't know what this means, don't
+   worry about it and just use field.data)
+
+
+This is it. It's pretty simple. A fully-featured plugin could
+look like this:
+
+--- %< ---
+def my_event_handler(trace_seq, event):
+    trace_seq.puts("myev: %u", long(event['myfield']))
+
+def register(pevent):
+    pevent.register_event_handler("subsys", "event_name",
+                                  my_event_handler)
+--- >% ---
+
+
+ Tips and tricks
+-----------------
+
+Be familiar with the struct module and use it, always
+checking endianness and potentially using pevent.file_endian.
+
+
+If you need access to pevent in your callbacks, simply
+pass it in yourself:
+
+--- %< ---
+def my_event_handler(pevent, trace_seq, event):
+    pass
+
+def register(pevent):
+    pevent.register_event_handler("subsys", "event_name",
+        lambda *args: my_event_handler(pevent, *args)
+    )
+--- >% ---
diff --git a/Makefile b/Makefile
index 239c05a..a4a89ed 100644
--- a/Makefile
+++ b/Makefile
@@ -439,12 +439,14 @@ clean:
 ##### PYTHON STUFF #####
 
 PYTHON_INCLUDES = `python-config --includes`
+PYTHON_LDFLAGS = `python-config --ldflags` \
+                $(shell python -c "import distutils.sysconfig; print distutils.sysconfig.get_config_var('LINKFORSHARED')")
 PYGTK_CFLAGS = `pkg-config --cflags pygtk-2.0`
 
-ctracecmd.so: $(TCMD_LIB_OBJS)
+ctracecmd.so: $(TCMD_LIB_OBJS) ctracecmd.i
         swig -Wall -python -noproxy ctracecmd.i
         gcc -fpic -c $(PYTHON_INCLUDES)  ctracecmd_wrap.c
-        $(CC) --shared $^ ctracecmd_wrap.o -o ctracecmd.so
+        $(CC) --shared $(TCMD_LIB_OBJS) ctracecmd_wrap.o -o ctracecmd.so
 
 ctracecmdgui.so: $(TRACE_VIEW_OBJS) $(LIB_FILE)
         swig -Wall -python -noproxy ctracecmdgui.i
@@ -457,6 +459,23 @@ python: ctracecmd.so
 PHONY += python-gui
 python-gui: ctracecmd.so ctracecmdgui.so 
 
+PHONY += python-plugin
+python-plugin: plugin_python.so python
+
+do_compile_python_plugin_obj =                  \
+        ($(print_plugin_obj_compile)            \
+        $(CC) -c $(CFLAGS) $(PYTHON_INCLUDES) -fPIC -o $@ $<)
+
+do_python_plugin_build =                        \
+        ($(print_plugin_build)                  \
+        $(CC) -shared $(PYTHON_LDFLAGS) -o $@ $<)
+
+plugin_python.o: %.o : $(src)/%.c
+        $(Q)$(do_compile_python_plugin_obj)
+
+plugin_python.so: %.so: %.o
+        $(Q)$(do_python_plugin_build)
+
 endif # skip-makefile
 
 PHONY += force
diff --git a/ctracecmd.i b/ctracecmd.i
index 51e98d5..a0baa3c 100644
--- a/ctracecmd.i
+++ b/ctracecmd.i
@@ -3,13 +3,14 @@
 %include "typemaps.i"
 %include "constraints.i"
 
+%nodefaultctor record;
+%nodefaultdtor record;
+
 %apply Pointer NONNULL { struct tracecmd_input *handle };
 %apply Pointer NONNULL { struct pevent *pevent };
-
-/* return a (rec,cpu) tuple in python */
-extern struct record *tracecmd_read_at(struct tracecmd_input *handle, 
-                                       unsigned long long offset,
-                                       int *OUTPUT);
+%apply Pointer NONNULL { struct format_field * };
+%apply unsigned long long *OUTPUT {unsigned long long *}
+%apply int *OUTPUT {int *}
 
 
 %{
@@ -17,26 +18,150 @@ extern struct record *tracecmd_read_at(struct tracecmd_input *handle,
 %}
 
 
-/* return python longs from unsigned long long functions */
-%typemap(out) unsigned long long {
-$result = PyLong_FromUnsignedLongLong((unsigned long long) $1);
+%typemap(in) PyObject *pyfunc {
+        if (!PyCallable_Check($input)) {
+                PyErr_SetString(PyExc_TypeError, "Need a callable object!");
+                return NULL;
+        }
+        $1 = $input;
 }
 
+%ignore python_callback;
 
 %inline %{
-PyObject *pevent_read_number_field_py(struct format_field *f, void *data)
+static int python_callback(struct trace_seq *s,
+                           struct record *record,
+                           struct event_format *event,
+                           void *context);
+
+PyObject *convert_pevent(unsigned long pevent)
+{
+        void *pev = (void *)pevent;
+        return SWIG_NewPointerObj(SWIG_as_voidptr(pev), SWIGTYPE_p_pevent, 0);
+}
+
+void py_pevent_register_event_handler(struct pevent *pevent, int id,
+                                      char *subsys, char *evname,
+                                      PyObject *pyfunc)
 {
-        unsigned long long val;
-        int ret;
-
-        ret = pevent_read_number_field(f, data, &val);
-        if (ret)
-                Py_RETURN_NONE;
-        else
-                return PyLong_FromUnsignedLongLong(val);
+        Py_INCREF(pyfunc);
+        pevent_register_event_handler(pevent, id, subsys, evname,
+                                      python_callback, pyfunc);
+}
+
+static PyObject *py_field_get_data(struct format_field *f, struct record *r)
+{
+        if (!strncmp(f->type, "__data_loc ", 11)) {
+                unsigned long long val;
+                int len, offset;
+
+                if (pevent_read_number_field(f, r->data, &val)) {
+                        PyErr_SetString(PyExc_TypeError,
+                                        "Field is not a valid number");
+                        return NULL;
+                }
+
+                /*
+                 * The actual length of the dynamic array is stored
+                 * in the top half of the field, and the offset
+                 * is in the bottom half of the 32 bit field.
+                 */
+                offset = val & 0xffff;
+                len = val >> 16;
+
+                return PyBuffer_FromMemory((char *)r->data + offset, len);
+        }
+
+        return PyBuffer_FromMemory((char *)r->data + f->offset, f->size);
+}
+
+static PyObject *py_field_get_str(struct format_field *f, struct record *r)
+{
+        if (!strncmp(f->type, "__data_loc ", 11)) {
+                unsigned long long val;
+                int offset;
+
+                if (pevent_read_number_field(f, r->data, &val)) {
+                        PyErr_SetString(PyExc_TypeError,
+                                        "Field is not a valid number");
+                        return NULL;
+                }
+
+                /*
+                 * The actual length of the dynamic array is stored
+                 * in the top half of the field, and the offset
+                 * is in the bottom half of the 32 bit field.
+                 */
+                offset = val & 0xffff;
+
+                return PyString_FromString((char *)r->data + offset);
+        }
+
+        return PyString_FromStringAndSize((char *)r->data + f->offset,
+                                strnlen((char *)r->data + f->offset, f->size));
+}
+
+static PyObject *py_format_get_keys(struct event_format *ef)
+{
+        PyObject *list;
+        struct format_field *f;
+
+        list = PyList_New(0);
+
+        for (f = ef->format.fields; f; f = f->next) {
+                if (PyList_Append(list, PyString_FromString(f->name))) {
+                        Py_DECREF(list);
+                        return NULL;
+                }
+        }
+
+        return list;
+}
+%}
+
+
+%wrapper %{
+static int python_callback(struct trace_seq *s,
+                           struct record *record,
+                           struct event_format *event,
+                           void *context)
+{
+        PyObject *arglist, *result;
+        int r = 0;
+
+        record->ref_count++;
+
+        arglist = Py_BuildValue("(OOO)",
+                SWIG_NewPointerObj(SWIG_as_voidptr(s),
+                                   SWIGTYPE_p_trace_seq, 0),
+                SWIG_NewPointerObj(SWIG_as_voidptr(record),
+                                   SWIGTYPE_p_record, 0),
+                SWIG_NewPointerObj(SWIG_as_voidptr(event),
+                                   SWIGTYPE_p_event_format, 0));
+
+        result = PyEval_CallObject(context, arglist);
+        Py_XDECREF(arglist);
+        if (result && result != Py_None) {
+                if (!PyInt_Check(result)) {
+                        PyErr_SetString(PyExc_TypeError,
+                                        "callback must return int");
+                        PyErr_Print();
+                        Py_XDECREF(result);
+                        return 0;
+                }
+                r = PyInt_AS_LONG(result);
+        } else if (result == Py_None)
+                r = 0;
+        else
+                PyErr_Print();
+
+        Py_XDECREF(result);
+
+        return r;
 }
 %}
 
+
 %ignore trace_seq_vprintf;
 
 /* SWIG can't grok these, define them to nothing */
diff --git a/parse-events.h b/parse-events.h
index be28245..400bc4c 100644
--- a/parse-events.h
+++ b/parse-events.h
@@ -43,7 +43,7 @@ struct record {
         int                     size;           /* size of data */
         void                    *data;
         int                     cpu;
-        int                     locked;         /* Do not allow freeing */
+        int                     ref_count;
         void                    *private;
 };
 
diff --git a/plugin_python.c b/plugin_python.c
new file mode 100644
index 0000000..164e774
--- /dev/null
+++ b/plugin_python.c
@@ -0,0 +1,136 @@
+#include <Python.h>
+#ifndef _GNU_SOURCE
+#define _GNU_SOURCE
+#endif
+#include <stdio.h>
+#include <dirent.h>
+#include <fnmatch.h>
+#include "trace-cmd.h"
+
+static const char pyload[] =
+"import imp, tracecmd, ctracecmd\n"
+"fn = r'%s'\n"
+"file = open(fn, 'r')\n"
+"try:\n"
+"   module = imp.load_source('%s', fn, file)\n"
+"   module.register(tracecmd.PEvent(ctracecmd.convert_pevent(pevent)))\n"
+"finally:\n"
+"   file.close()\n";
+
+static void load_plugin(PyObject *globals, char *path, const char *name)
+{
+        int len = strlen(path) + strlen(name) + 2;
+        int nlen = strlen(name) + 1;
+        char *full = malloc(len);
+        char *n = malloc(nlen);
+        char *load;
+        PyObject *res;
+
+        if (!full || !n)
+                return;
+
+        strcpy(full, path);
+        strcat(full, "/");
+        strcat(full, name);
+
+        strcpy(n, name);
+        n[nlen - 4] = '\0';
+
+        asprintf(&load, pyload, full, n);
+        if (!load)
+                return;
+
+        res = PyRun_String(load, Py_file_input, globals, globals);
+        if (!res) {
+                fprintf(stderr, "failed loading %s\n", full);
+                PyErr_Print();
+        } else
+                Py_DECREF(res);
+
+        free(load);
+}
+
+static int load_plugins(PyObject *globals, char *path)
+{
+        struct dirent *dent;
+        struct stat st;
+        DIR *dir;
+        int ret;
+
+        ret = stat(path, &st);
+        if (ret < 0)
+                return -1;
+
+        if (!S_ISDIR(st.st_mode))
+                return -1;
+
+        dir = opendir(path);
+        if (!dir)
+                return -1;
+
+        while ((dent = readdir(dir))) {
+                const char *name = dent->d_name;
+
+                if (fnmatch("*.py", name, FNM_PERIOD))
+                        continue;
+
+                load_plugin(globals, path, name);
+        }
+
+        closedir(dir);
+
+        return 0;
+}
+
+#define LOCAL_PLUGIN_DIR        ".trace-cmd/python"
+
+int PEVENT_PLUGIN_LOADER(struct pevent *pevent)
+{
+        char *home;
+        char *path;
+        int ret;
+        PyObject *globals, *m, *py_pevent, *str;
+
+        home = getenv("HOME");
+        if (!home)
+                return 0;
+
+        Py_Initialize();
+
+        m = PyImport_AddModule("__main__");
+        globals = PyModule_GetDict(m);
+
+        str = PyString_FromString("pevent");
+        if (!str)
+                return -ENOMEM;
+
+        py_pevent = PyLong_FromUnsignedLong((unsigned long)pevent);
+        if (!py_pevent)
+                return -ENOMEM;
+
+        if (PyDict_SetItem(globals, str, py_pevent))
+                fprintf(stderr, "failed to insert pevent\n");
+
+        Py_DECREF(py_pevent);
+        Py_DECREF(str);
+
+        path = malloc(strlen(home) + strlen(LOCAL_PLUGIN_DIR) + 2);
+        if (!path)
+                return -1;
+
+        strcpy(path, home);
+        strcat(path, "/");
+        strcat(path, LOCAL_PLUGIN_DIR);
+
+        ret = load_plugins(globals, path);
+
+        free(path);
+
+        return ret;
+}
+
+int PEVENT_PLUGIN_UNLOADER(void)
+{
+        Py_Finalize();
+        return 0;
+}
diff --git a/trace-ftrace.c b/trace-ftrace.c
index af9ac8d..7cd5032 100644
--- a/trace-ftrace.c
+++ b/trace-ftrace.c
@@ -255,8 +255,13 @@ fgraph_ent_handler(struct trace_seq *s, struct record *record,
                 return trace_seq_putc(s, '!');
 
         rec = tracecmd_peek_data(tracecmd_curr_thread_handle, cpu);
-        if (rec)
-                rec = get_return_for_leaf(s, cpu, pid, val, rec);
+        if (rec) {
+                struct record *tmp;
+
+                tmp = get_return_for_leaf(s, cpu, pid, val, rec);
+                free_record(rec);
+                rec = tmp;
+        }
 
         if (rec) {
                 /*
diff --git a/trace-input.c b/trace-input.c
index c39004a..9db96c7 100644
--- a/trace-input.c
+++ b/trace-input.c
@@ -660,8 +660,13 @@ void free_record(struct record *record)
         if (!record)
                 return;
 
-        if (record->locked)
-                die("freeing record when it is locked!");
+        if (!record->ref_count)
+                die("record ref count is zero!");
+
+        record->ref_count--;
+        if (record->ref_count)
+                return;
+
         record->data = NULL;
 
         __free_record(record);
@@ -675,7 +680,8 @@ static void free_next(struct tracecmd_input *handle, int cpu)
                 return;
 
         handle->cpu_data[cpu].next = NULL;
-        __free_record(record);
+
+        free_record(record);
 }
 
 /*
@@ -870,6 +876,7 @@ read_old_format(struct tracecmd_input *handle, void **ptr, int cpu)
                 return NULL;
         memset(data, 0, sizeof(*data));
 
+        data->ref_count = 1;
         data->ts = handle->cpu_data[cpu].timestamp;
         data->size = length;
         data->data = *ptr;
@@ -902,11 +909,12 @@ peek_event(struct tracecmd_input *handle, unsigned long long offset,
         free_next(handle, cpu);
 
         do {
-                free_record(record);
                 record = tracecmd_peek_data(handle, cpu);
                 if (record && (record->offset + record->record_size) > offset)
                         break;
-                record = tracecmd_read_data(handle, cpu);
+                free_record(record);
+
+                free_next(handle, cpu);
         } while (record);
 
         return record;
@@ -919,8 +927,10 @@ read_event(struct tracecmd_input *handle, unsigned long long offset,
         struct record *record;
 
         record = peek_event(handle, offset, cpu);
-        if (record)
+        if (record) {
+                free_record(record);
                 record = tracecmd_read_data(handle, cpu);
+        }
         return record;
 }
 
@@ -1301,7 +1311,7 @@ int tracecmd_set_cursor(struct tracecmd_input *handle,
         if (get_page(handle, cpu, page_offset) < 0)
                 return -1;
 
-        peek_event(handle, offset, cpu);
+        free_record(peek_event(handle, offset, cpu));
 
         return 0;
 }
@@ -1429,6 +1439,7 @@ tracecmd_translate_data(struct tracecmd_input *handle,
                 return NULL;
         memset(record, 0, sizeof(*record));
 
+        record->ref_count = 1;
         record->data = ptr;
         type_len = translate_data(handle, &record->data, &record->ts, &record->size);
         switch (type_len) {
@@ -1451,8 +1462,6 @@ tracecmd_translate_data(struct tracecmd_input *handle,
  *
  * This returns the record at the current location of the CPU
  * iterator. It does not increment the CPU iterator.
- *
- * NOTE: Do not free the record returned, it is stored in the @handle.
  */
 struct record *
 tracecmd_peek_data(struct tracecmd_input *handle, int cpu)
@@ -1479,8 +1488,10 @@ tracecmd_peek_data(struct tracecmd_input *handle, int cpu)
                 if (!record->data)
                         die("Something freed the record");
 
-                if (handle->cpu_data[cpu].timestamp == record->ts)
+                if (handle->cpu_data[cpu].timestamp == record->ts) {
+                        record->ref_count++;
                         return record;
+                }
 
                 /*
                  * The timestamp changed, which means the cached
@@ -1553,6 +1564,7 @@ read_again:
         record->data = ptr;
         record->offset = handle->cpu_data[cpu].offset + index;
         record->missed_events = missed_events;
+        record->ref_count = 2; /* will be returned and stored in page */
 
         ptr += length;
 
@@ -1561,7 +1573,6 @@ read_again:
 
         record->record_size = handle->cpu_data[cpu].index - index;
         record->private = page;
-        record->locked = 1;
         page->ref_count++;
 
         return record;
@@ -1585,7 +1596,7 @@ tracecmd_read_data(struct tracecmd_input *handle, int cpu)
         record = tracecmd_peek_data(handle, cpu);
         handle->cpu_data[cpu].next = NULL;
         if (record)
-                record->locked = 0;
+                record->ref_count--;
 
         return record;
 }
@@ -1627,6 +1638,7 @@ tracecmd_read_next_data(struct tracecmd_input *handle, int *rec_cpu)
                         ts = record->ts;
                         next = cpu;
                 }
+                free_record(record);
         }
 
         if (next >= 0) {
@@ -1647,13 +1659,12 @@ tracecmd_read_next_data(struct tracecmd_input *handle, int *rec_cpu)
  * @record is the first record, NULL is returned. The cursor is set
  * as if the previous record was read by tracecmd_read_data().
  *
- * @record can not be NULL, otherwise NULL is returned.
+ * @record can not be NULL, otherwise NULL is returned; the
+ * record ownership goes to this function.
  *
  * Note, this is not that fast of an algorithm, since it needs
  * to build the timestamp for the record.
  *
- * Note 2: This may free any record allocoted with tracecmd_peek_data().
- *
  * The record returned must be freed with free_record().
  */
 struct record *
@@ -1674,7 +1685,7 @@ tracecmd_read_prev(struct tracecmd_input *handle, struct record *record)
         page_offset = calc_page_offset(handle, offset);
         index = offset - page_offset;
 
-        /* Note, the record passed in could have been a peek */
+        free_record(record);
         free_next(handle, cpu);
 
         /* Reset the cursor */
diff --git a/trace-plot-cpu.c b/trace-plot-cpu.c
index 50d720b..fdfbdf7 100644
--- a/trace-plot-cpu.c
+++ b/trace-plot-cpu.c
@@ -137,7 +137,7 @@ static int cpu_plot_display_last_event(struct graph_info *ginfo,
         record = tracecmd_peek_data(ginfo->handle, cpu);
         if (record)
                 offset = record->offset;
-        /* Don't need to free a peek */
+        free_record(record);
 
         tracecmd_set_cpu_to_timestamp(ginfo->handle, cpu, time);
 
diff --git a/trace-plot-task.c b/trace-plot-task.c
index 0c9f8e0..71fa731 100644
--- a/trace-plot-task.c
+++ b/trace-plot-task.c
@@ -183,6 +183,7 @@ static struct offset_cache *save_offsets(struct graph_info *ginfo)
                 record = tracecmd_peek_data(ginfo->handle, cpu);
                 if (record)
                         offsets->offsets[cpu] = record->offset;
+                free_record(record);
         }
 
         return offsets;
diff --git a/trace-util.c b/trace-util.c
index 7c0481a..4fd1d38 100644
--- a/trace-util.c
+++ b/trace-util.c
@@ -212,7 +212,7 @@ load_plugin(struct pevent *pevent, struct plugin_list *plugin_list,
         strcat(plugin, "/");
         strcat(plugin, file);
 
-        handle = dlopen(plugin, RTLD_NOW);
+        handle = dlopen(plugin, RTLD_NOW | RTLD_GLOBAL);
         if (!handle) {
                 warning("cound not load plugin '%s'\n%s\n",
                         plugin, dlerror());
diff --git a/tracecmd.py b/tracecmd.py
index 6b05e23..ad80ccd 100644
--- a/tracecmd.py
+++ b/tracecmd.py
@@ -18,6 +18,7 @@
 # 2009-Dec-17:  Initial version by Darren Hart <dvhltc@us.ibm.com>
 #
 
+from functools import update_wrapper
 from ctracecmd import *
 
 """
@@ -31,13 +32,33 @@ and it is recommended applications not use it directly.
 TODO: consider a complete class hierarchy of ftrace events...
 """
 
+def cached_property(func, name=None):
+    if name is None:
+        name = func.__name__
+    def _get(self):
+        try:
+            return self.__cached_properties[name]
+        except AttributeError:
+            self.__cached_properties = {}
+        except KeyError:
+            pass
+        value = func(self)
+        self.__cached_properties[name] = value
+        return value
+    update_wrapper(_get, func)
+    def _del(self):
+        self.__cached_properties.pop(name, None)
+    return property(_get, None, _del)
+
 class Event(object):
-    def __init__(self, trace, record, cpu):
-        self.trace = trace
-        self.rec = record
-        self.cpu = cpu
-        type = pevent_data_type(trace.pe, record)
-        self.format = pevent_data_event_from_type(trace.pe, type)
+    """
+    This class can be used to access event data
+    according to an event's record and format.
+    """
+    def __init__(self, pevent, record, format):
+        self._pevent = pevent
+        self._record = record
+        self._format = format
 
     def __str__(self):
         return "%d.%d CPU%d %s: pid=%d comm=%s type=%d" % \
@@ -45,35 +66,105 @@ class Event(object):
                 self.num_field("common_pid"), self.comm, self.type)
 
     def __del__(self):
-        free_record(self.rec);
+        free_record(self._record)
+
+    def __getitem__(self, n):
+        f = pevent_find_field(self._format, n)
+        if f is None:
+            raise KeyError("no field '%s'" % n)
+        return Field(self._record, f)
 
+    def keys(self):
+        return py_format_get_keys(self._format)
 
-    # TODO: consider caching the results of the properties
-    @property
+    @cached_property
     def comm(self):
-        return self.trace.comm_from_pid(self.pid)
+        return pevent_data_comm_from_pid(self._pevent, self.pid)
 
-    @property
+    @cached_property
+    def cpu(self):
+        return record_cpu_get(self._record)
+
+    @cached_property
     def name(self):
-        return event_format_name_get(self.format)
+        return event_format_name_get(self._format)
 
-    @property
+    @cached_property
     def pid(self):
-        return pevent_data_pid(self.trace.pe, self.rec)
+        return pevent_data_pid(self._pevent, self._record)
 
-    @property
+    @cached_property
     def ts(self):
-        return record_ts_get(self.rec)
+        return record_ts_get(self._record)
 
-    @property
+    @cached_property
     def type(self):
-        return pevent_data_type(self.trace.pe, self.rec)
+        return pevent_data_type(self._pevent, self._record)
 
     def num_field(self, name):
-        f = pevent_find_any_field(self.format, name)
-        val = pevent_read_number_field_py(f, record_data_get(self.rec))
+        f = pevent_find_any_field(self._format, name)
+        if f is None:
+            return None
+        ret, val = pevent_read_number_field(f, record_data_get(self._record))
+        if ret:
+            return None
         return val
 
+    def str_field(self, name):
+        f = pevent_find_any_field(self._format, name)
+        if f is None:
+            return None
+        return py_field_get_str(f, self._record)
+
+class TraceSeq(object):
+    def __init__(self, trace_seq):
+        self._trace_seq = trace_seq
+
+    def puts(self, s):
+        return trace_seq_puts(self._trace_seq, s)
+
+class FieldError(Exception):
+    pass
+
+class Field(object):
+    def __init__(self, record, field):
+        self._record = record
+        self._field = field
+
+    @cached_property
+    def data(self):
+        return py_field_get_data(self._field, self._record)
+
+    def __long__(self):
+        ret, val =  pevent_read_number_field(self._field,
+                                             record_data_get(self._record))
+        if ret:
+            raise FieldError("Not a number field")
+        return val
+    __int__ = __long__
+
+    def __str__(self):
+        return py_field_get_str(self._field, self._record)
+
+class PEvent(object):
+    def __init__(self, pevent):
+        self._pevent = pevent
+
+    def _handler(self, cb, s, record, event_fmt):
+        return cb(TraceSeq(s), Event(self._pevent, record, event_fmt))
+
+    def register_event_handler(self, subsys, event_name, callback):
+        l = lambda s, r, e: self._handler(callback, s, r, e)
+
+        py_pevent_register_event_handler(
+                  self._pevent, -1, subsys, event_name, l)
+
+    @cached_property
+    def file_endian(self):
+        if pevent_is_file_bigendian(self._pevent):
+            return '>'
+        return '<'
+
 
 class FileFormatError(Exception):
     pass
@@ -86,45 +177,43 @@ class Trace(object):
     used to manage the trace and extract events from it.
     """
     def __init__(self, filename):
-        self.handle = tracecmd_open(filename)
+        self._handle = tracecmd_alloc(filename)
 
-        if tracecmd_read_headers(self.handle):
+        if tracecmd_read_headers(self._handle):
             raise FileFormatError("Invalid headers")
 
-        if tracecmd_init_data(self.handle):
+        if tracecmd_init_data(self._handle):
             raise FileFormatError("Failed to init data")
 
-        self.pe = tracecmd_get_pevent(self.handle)
+        self._pevent = tracecmd_get_pevent(self._handle)
 
-    @property
+    @cached_property
     def cpus(self):
-        return tracecmd_cpus(self.handle)
+        return tracecmd_cpus(self._handle)
 
     def read_event(self, cpu):
-        rec = tracecmd_read_data(self.handle, cpu)
+        rec = tracecmd_read_data(self._handle, cpu)
         if rec:
-            #rec.acquire()
-            #rec.thisown = 1
-            return Event(self, rec, cpu)
+            type = pevent_data_type(self._pevent, rec)
+            format = pevent_data_event_from_type(self._pevent, type)
+            # rec ownership goes over to Event instance
+            return Event(self._pevent, rec, format)
         return None
 
     def read_event_at(self, offset):
-        res = tracecmd_read_at(self.handle, offset)
+        res = tracecmd_read_at(self._handle, offset)
         # SWIG only returns the CPU if the record is None for some reason
         if isinstance(res, int):
             return None
-        rec,cpu = res
-        #rec.acquire()
-        #rec.thisown = 1
-        ev = Event(self, rec, cpu)
-        return ev
+        rec, cpu = res
+        type = pevent_data_type(self._pevent, rec)
+        format = pevent_data_event_from_type(self._pevent, type)
+        # rec ownership goes over to Event instance
+        return Event(self._pevent, rec, format)
 
     def peek_event(self, cpu):
         pass
 
-    def comm_from_pid(self, pid):
-        return pevent_data_comm_from_pid(self.pe, pid)
-
 
 # Basic builtin test, execute module directly
 if __name__ == "__main__":