Commit 1046c4f5 authored by Ian Murdock's avatar Ian Murdock

Doc fixes/updates:

Fixed typo in API (s/event_notification/event_notification_t/).

Tell user (in README) to configure Elvin library with --enable-threads
to enable threaded API support.

Removed instructions on enabling server discovery feature (now optional).

Document event_register interface changes ("threaded" arguement, which
allows caller to choose between the thread-safe "threaded" API and the
simpler "sync" API).

Mention (in API) that event_notify and event_schedule don't deallocate
notification.
parent b52afe4d
......@@ -2,13 +2,22 @@
#include <event.h>
event_handle_t event_register(char *name);
event_handle_t event_register(char *name, int threaded);
Register with the testbed event system. NAME specifies the name of
the event server. Returns a pointer to a handle that may be passed
to other event system routines if the operation is successful, NULL
otherwise.
The THREADED parameter should be set to 1 if the registering
client is multi-threaded. If THREADED is 1, the event
library will call routines that are thread-safe, and event
notifications will be dispatched using background threads (i.e.,
the client will supply its own event loop). If THREADED is 0, event
notifications will be dispatched using an event system-provided
event loop, and the client must call event_main after connecting in
order to receive notifications.
Elvin note: NAME is a URL of the form "elvin:/[protocol
stack]/[endpoint]", where a protocol stack names a transport
module, a security module, and a marshaling module as a comma
......@@ -53,6 +62,10 @@
have attributes added to it by event_notification_put_*.
Returns non-zero if the operation is successful, 0 otherwise.
Note that NOTIFICATION is not deallocated by event_notify. The
caller is responsible for deallocating the notification when it
is finished with it.
* event_schedule: Schedule an event notification
......@@ -72,6 +85,10 @@
event_notify sends notifications immediately,
whereas event_schedule sends notifications at some later time.
Note that NOTIFICATION is not deallocated by event_schedule.
The caller is responsible for deallocating the notification
when it is finished with it.
* event_notification_alloc: Allocate an event notification
......
......@@ -6,17 +6,17 @@ To build the event system, you first need to obtain the Elvin publish/
subscribe system. You need both the Elvin client library (libelvin)
and the Elvin server (elvind). You may either get them directly from
http://elvin.dstc.com/ or from the Flux CVS repository (module names
"libelvin" and "elvind"). Once the Elvin client library is built and
installed, you may build the event system by doing a "make".
"libelvin" and "elvind"). Be sure to configure the Elvin library with
"--enable-threads" to build support for Elvin's thread-safe
"threaded" API. Once the Elvin client library is built and installed,
you may build the event system by doing a "make".
USING THE EVENT SYSTEM
Before you may use the event system, you must configure the Elvin
server. A sample configuration file may be found in the etc
directory. The important parts are (1) to specify a scope
of "testbed", because that's the scope the event library operates
in; and (2) to set the "default" parameter to "on", so
that clients may find the server without having to specify a URL.
Before you may use the event system, you must configure the
Elvin server. The default Elvin configuration file should suffice. If
you want to use Elvin's server discovery protocol, you will need
to set "scope" and "default" accordingly (see the Elvin documentation).
Next, you need to start the Elvin server ("elvind") on a machine in
the local network. The Elvin server is responsible for routing event
......
......@@ -7,7 +7,7 @@
* @COPYRIGHT@
*/
static char rcsid[] = "$Id: event.c,v 1.9 2002-02-19 15:45:24 imurdock Exp $";
static char rcsid[] = "$Id: event.c,v 1.10 2002-02-19 16:18:21 imurdock Exp $";
#include <stdio.h>
#include <assert.h>
......@@ -25,6 +25,15 @@ static char hostname[MAXHOSTNAMELEN];
* to other event system routines if the operation is successful, NULL
* otherwise.
*
* The THREADED parameter should be set to 1 if the registering
* client is multi-threaded. If THREADED is 1, the event
* library will call routines that are thread-safe, and event
* notifications will be dispatched using background threads (i.e.,
* the client will supply its own event loop). If THREADED is 0, event
* notifications will be dispatched using an event system-provided
* event loop, and the client must call event_main after connecting in
* order to receive notifications.
*
* Elvin note: NAME is a URL of the form "elvin:/[protocol
* stack]/[endpoint]", where a protocol stack names a transport
* module, a security module, and a marshaling module as a comma
......@@ -201,6 +210,10 @@ event_main(event_handle_t handle)
* allocated by event_notification_alloc, and may optionally
* have attributes added to it by event_notification_put_*.
* Returns non-zero if the operation is successful, 0 otherwise.
*
* Note that NOTIFICATION is not deallocated by event_notify. The
* caller is responsible for deallocating the notification when it
* is finished with it.
*/
int
......@@ -236,6 +249,10 @@ event_notify(event_handle_t handle, event_notification_t notification)
* This function essentially operates as a deferred event_notify.
* event_notify sends notifications immediately,
* whereas event_schedule sends notifications at some later time.
*
* Note that NOTIFICATION is not deallocated by event_schedule.
* The caller is responsible for deallocating the notification
* when it is finished with it.
*/
int
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment