CVS log for specs/event/Event.api
	Help

Request diff between arbitrary revisions

From a posting from Joe DiMartino dated 12/19/2002:

Hello OCF!

Here is a cut at the event notification API without membership, etc.
I have gutted most of the extra text about the scope and context that
this event service expects.

Note: I have not spent any time to figure out the docbook format that
was suggested.  It's still ascii, but changed to be more man-page'ish.

Highlights:
h1. removed all non-event subject matter (membership, etc)

h2. name changes for clarity:
		replaced 'register' with 'subscribe',
		replaced 'class' with 'topic',
		replaced 'callback' with 'on_event'

h3. added get_event() interface

h4. changed semantics of handle_events() to differ from get_event().
	get_event() is the manual way to process events and requires
	the use of poll/select and a file descriptor.  handle_events()
	[notice the plural now] will pass control to the event service
	to make calling the on_event functions seem more automatic and
	less like a clunky get_event().


Outstanding issues:
i1.  file descriptor vs. event descriptor (was token)
	If you recall, v0.2 returned a "token" from register() that
	was passed to subsequent calls and needed to be converted to
	a file descriptor for poll/select.  A poll/select is inevitable
	in this programming model, so in v0.3 the token was removed
	and a file descriptor was returned instead.  This cut out the
	middle man (and a function or two), but Ram seems to still
	want a token of some sort.

	In this go, you will notice an "event descriptor" that takes
	the place of the v0.2 token.  There is also a way to convert
	the ed into a file descriptor.  I would prefer to put it back
	to a simple file descriptor.

i2. on_event function replacement
	In v0.2, there was a "set_callback" routine to swap out the
	current on_event (callback) function.  That was removed in
	v0.3 because many thought it was extra complexity that would
	not be useful.  Alan disagrees, however, and wants it back in.

	It is still absent from this pre-draft.

i3. publish interfaces
	This partial pre-draft still does not cover message allocation,
	message stuffing, and message/event publishing interfaces.

i4. distributed vs. local
	There was some discussion once about the scope of delivery for
	events.  If an instance of the event service runs on every node
	in a cluster, should all events in each event topic be seen at
	all locations?  Or, should there be some provision for "local
	only" topics, such as "this node's connectivity".

	In addition, making the event service available as a cluster-
	wide service (for applications external to the cluster) has
	slightly different implications than an event service intended
	for the cluster (internal) components.

i5. creation of event topics
	This is not covered yet.  It can be done administratively or
	with programming interfaces or both.  This issue is tightly
	coupled with #i4, as there may be a need to specify "local" or
	"global" at topic creation time.  In either case, there is
	an event name space issue if it needs to be kept coherent
	across the cluster.

I'm sure there are more outstanding issues, but I can't think of them
just now...

As ever, happy reading.

Happy Holidays!
- Joe DiMartino

From a posting from Joe DiMartino dated 8/16/2002.

Not too long ago, in a discussion far far away...

there was talk about using separate file descriptors per event class,
and other simplifications of the API interfaces.  The topic quickly
changed to partial membership and other semantic changes to the
membership events.  Then a series of synchronous interfaces were
proposed to replace the asynchronous callbacks.

Updates to the draft API document were delayed while discussions
continued in the hopes of incorporating partial membership semantics
along with the promised separate file descriptor support.

Bottom line: The partial membership stuff will take longer to sort
out, and I wanted to commit the rest to paper before I forgot. :-)


This draft proposal updates the programming interface (API) section
to match the examples posted previously, and provides support for
separate file descriptors per event class.  It does NOT include any
updates (except for typos and clarifications) to the membership events
and their semantics - i.e., partial membership is still not covered yet.
Also, this document does not include any of the proposed synchronous
get_* interfaces.

Best regards,
- Joe DiMartino

Version 0.2 of the Event API.  Posted by Joe DiMartino 6/7/2002

From a posting from Joe DiMartino dated 4/12/2002:
Hello OCF list,

Enclosed, please find the initial draft proposal for the Cluster Event
Notification API (v0.1).

As suggested by Bruce Walker on a previous OCF posting, we have decided
to give only one part of this document at a time for general review.

This document will EVENTUALLY cover:

	a. event notification service
	b. connectivity events and semantics
	c. membership events and semantics
	d. group messaging events and semantics

Currently, this text covers only (a).  The Data Structures section
hints at some events for (b) (c) and (d), but please don't dwell on
that now.

The examples section is intended to increase the understanding of
the event model.  However, there are no examples of in-kernel usage
and three user-level examples are combined into one.

Happy Reading!

Respectfully,
- Ram Pai and Joe DiMartino