src/pkg/exp/ogle/event.go

// Copyright 2009 The Go Authors.  All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

package ogle

import (
	"debug/proc"
	"fmt"
	"os"
)

/*
 * Hooks and events
 */

// An EventHandler is a function that takes an event and returns a
// response to that event and possibly an error.  If an event handler
// returns an error, the process stops and no other handlers for that
// event are executed.
type EventHandler func(e Event) (EventAction, os.Error)

// An EventAction is an event handler's response to an event.  If all
// of an event's handlers execute without returning errors, their
// results are combined as follows: If any handler returned
// EAContinue, then the process resumes (without returning from
// WaitStop); otherwise, if any handler returned EAStop, the process
// remains stopped; otherwise, if all handlers returned EADefault, the
// process resumes.  A handler may return EARemoveSelf bit-wise or'd
// with any other action to indicate that the handler should be
// removed from the hook.
type EventAction int

const (
	EARemoveSelf EventAction = 0x100
	EADefault    EventAction = iota
	EAStop
	EAContinue
)

// A EventHook allows event handlers to be added and removed.
type EventHook interface {
	AddHandler(EventHandler)
	RemoveHandler(EventHandler)
	NumHandler() int
	handle(e Event) (EventAction, os.Error)
	String() string
}

// EventHook is almost, but not quite, suitable for user-defined
// events.  If we want user-defined events, make EventHook a struct,
// special-case adding and removing handlers in breakpoint hooks, and
// provide a public interface for posting events to hooks.

type Event interface {
	Process() *Process
	Goroutine() *Goroutine
	String() string
}

type commonHook struct {
	// Head of handler chain
	head *handler
	// Number of non-internal handlers
	len int
}

type handler struct {
	eh EventHandler
	// True if this handler must be run before user-defined
	// handlers in order to ensure correctness.
	internal bool
	// True if this handler has been removed from the chain.
	removed bool
	next    *handler
}

func (h *commonHook) AddHandler(eh EventHandler) {
	h.addHandler(eh, false)
}

func (h *commonHook) addHandler(eh EventHandler, internal bool) {
	// Ensure uniqueness of handlers
	h.RemoveHandler(eh)

	if !internal {
		h.len++
	}
	// Add internal handlers to the beginning
	if internal || h.head == nil {
		h.head = &handler{eh, internal, false, h.head}
		return
	}
	// Add handler after internal handlers
	// TODO(austin) This should probably go on the end instead
	prev := h.head
	for prev.next != nil && prev.internal {
		prev = prev.next
	}
	prev.next = &handler{eh, internal, false, prev.next}
}

func (h *commonHook) RemoveHandler(eh EventHandler) {
	plink := &h.head
	for l := *plink; l != nil; plink, l = &l.next, l.next {
		if l.eh == eh {
			if !l.internal {
				h.len--
			}
			l.removed = true
			*plink = l.next
			break
		}
	}
}

func (h *commonHook) NumHandler() int { return h.len }

func (h *commonHook) handle(e Event) (EventAction, os.Error) {
	action := EADefault
	plink := &h.head
	for l := *plink; l != nil; plink, l = &l.next, l.next {
		if l.removed {
			continue
		}
		a, err := l.eh(e)
		if a&EARemoveSelf == EARemoveSelf {
			if !l.internal {
				h.len--
			}
			l.removed = true
			*plink = l.next
			a &^= EARemoveSelf
		}
		if err != nil {
			return EAStop, err
		}
		if a > action {
			action = a
		}
	}
	return action, nil
}

type commonEvent struct {
	// The process of this event
	p *Process
	// The goroutine of this event.
	t *Goroutine
}

func (e *commonEvent) Process() *Process { return e.p }

func (e *commonEvent) Goroutine() *Goroutine { return e.t }

/*
 * Standard event handlers
 */

// EventPrint is a standard event handler that prints events as they
// occur.  It will not cause the process to stop.
func EventPrint(ev Event) (EventAction, os.Error) {
	// TODO(austin) Include process name here?
	fmt.Fprintf(os.Stderr, "*** %v\n", ev.String())
	return EADefault, nil
}

// EventStop is a standard event handler that causes the process to stop.
func EventStop(ev Event) (EventAction, os.Error) {
	return EAStop, nil
}

/*
 * Breakpoints
 */

type breakpointHook struct {
	commonHook
	p  *Process
	pc proc.Word
}

// A Breakpoint event occurs when a process reaches a particular
// program counter.  When this event is handled, the current goroutine
// will be the goroutine that reached the program counter.
type Breakpoint struct {
	commonEvent
	osThread proc.Thread
	pc       proc.Word
}

func (h *breakpointHook) AddHandler(eh EventHandler) {
	h.addHandler(eh, false)
}

func (h *breakpointHook) addHandler(eh EventHandler, internal bool) {
	// We register breakpoint events lazily to avoid holding
	// references to breakpoints without handlers.  Be sure to use
	// the "canonical" breakpoint if there is one.
	if cur, ok := h.p.breakpointHooks[h.pc]; ok {
		h = cur
	}
	oldhead := h.head
	h.commonHook.addHandler(eh, internal)
	if oldhead == nil && h.head != nil {
		h.p.proc.AddBreakpoint(h.pc)
		h.p.breakpointHooks[h.pc] = h
	}
}

func (h *breakpointHook) RemoveHandler(eh EventHandler) {
	oldhead := h.head
	h.commonHook.RemoveHandler(eh)
	if oldhead != nil && h.head == nil {
		h.p.proc.RemoveBreakpoint(h.pc)
		h.p.breakpointHooks[h.pc] = nil, false
	}
}

func (h *breakpointHook) String() string {
	// TODO(austin) Include process name?
	// TODO(austin) Use line:pc or at least sym+%#x
	return fmt.Sprintf("breakpoint at %#x", h.pc)
}

func (b *Breakpoint) PC() proc.Word { return b.pc }

func (b *Breakpoint) String() string {
	// TODO(austin) Include process name and goroutine
	// TODO(austin) Use line:pc or at least sym+%#x
	return fmt.Sprintf("breakpoint at %#x", b.pc)
}

/*
 * Goroutine create/exit
 */

type goroutineCreateHook struct {
	commonHook
}

func (h *goroutineCreateHook) String() string { return "goroutine create" }

// A GoroutineCreate event occurs when a process creates a new
// goroutine.  When this event is handled, the current goroutine will
// be the newly created goroutine.
type GoroutineCreate struct {
	commonEvent
	parent *Goroutine
}

// Parent returns the goroutine that created this goroutine.  May be
// nil if this event is the creation of the first goroutine.
func (e *GoroutineCreate) Parent() *Goroutine { return e.parent }

func (e *GoroutineCreate) String() string {
	// TODO(austin) Include process name
	if e.parent == nil {
		return fmt.Sprintf("%v created", e.t)
	}
	return fmt.Sprintf("%v created by %v", e.t, e.parent)
}

type goroutineExitHook struct {
	commonHook
}

func (h *goroutineExitHook) String() string { return "goroutine exit" }

// A GoroutineExit event occurs when a Go goroutine exits.
type GoroutineExit struct {
	commonEvent
}

func (e *GoroutineExit) String() string {
	// TODO(austin) Include process name
	//return fmt.Sprintf("%v exited", e.t);
	// For debugging purposes
	return fmt.Sprintf("goroutine %#x exited", e.t.g.addr().base)
}