🚀 go-pugleaf

I'm posting this article to describe the way ToolTalk handles file-based
scoping mechanisms and when ToolTalk does and does not use the ToolTalk
database server for handling file-based scoping mechanisms.  Specifically,
because of a bug in the current release, ToolTalk does not use the DB
server for any type of scoping (other then TT_OBJECT scoping) unless an
explicit tt_file_join call is made.

The following is an explanation of when the DB server is and is not used
and how the DB server is used for scoping and how the various file-based
scoping methods work.

Brief Overview of the TT DB Server Duties
-----------------------------------------
In the current release of ToolTalk, the DB server is used to store 3 types
of infomration:

	1) Storage of ToolTalk objects specs (see the tt_spec_write and
	   and the other tt_spec_* API calls).

	2) Storage of ToolTalk session IDs of sessions with clients that
	   have joined a file via the tt_file_join call.

	3) Storage of a file-scoped (NOT file-in-session scoped) message
	   that is queued because the message disposition is TT_QUEUED
	   and a handler has not yet been started that can handle the
	   message.

File-based Scoping in Patterns
------------------------------
With patterns, there 3 types of scopes that use files:

	TT_FILE, TT_BOTH, TT_FILE_IN_SESSION, TT_SESSION+tt_pattern_file_add()

TT_FILE scopes to just a file.  A session attribute may be set on this type
of pattern to provide a file-in-session-like scoping, but a tt_session_join
will NOT update the session attribute of a pattern that is TT_FILE scoped.

TT_BOTH scopes to the union of interest in the file and the session.  A
pattern with just this scope will match messages that are scoped to either
the file and/or the session.

TT_FILE_IN_SESSION scopes to the intersection of interest in the file and
the session.  A pattern with just this scope will only match messages
that are scoped to both the file and session.

Using the TT_SESSION scope and calling tt_pattern_file_add provides exactly
the same type of pattern scoping as TT_FILE_IN_SESSION, except, if a
tt_file_join call is made, it will add files to TT_FILE, TT_BOTH, and
TT_FILE_IN_SESSION scoped patterns, but NOT to TT_SESSION scoped patterns.
This is important because patterns that were registered via a tt_ptype_declare
call can only have files added to them via a tt_file_join call.

In the case of the TT_FILE_IN_SESSION scope, all you need to do is
create a pattern, add the TT_FILE_IN_SESSION scope to the pattern, add
a session to the pattern (or call tt_session_join after registering the
pattern), add a file to the pattern, and then register the pattern.
The following 2 examples register an equivalent pattern (sans error
checking):

	Example 1:
	----------
	tt_open();

	Tt_pattern pat = tt_create_pattern();
	tt_pattern_scope_add(pat, TT_FILE_IN_SESSION);
	tt_pattern_file_add(pat, file);
	tt_pattern_session_add(pat, tt_default_session());
	tt_pattern_register(pat);

	Example 2:
	----------
	tt_open();

	Tt_pattern pat = tt_create_pattern();
	tt_pattern_scope_add(pat, TT_FILE_IN_SESSION);
	tt_pattern_file_add(pat, file);
	tt_pattern_register(pat);
	tt_session_join(tt_default_session());

Because TT_FILE_IN_SESSION scope is the intersection of file interest
and session interest, all the information required to properly match
similarly scoped messages can be stored in the ToolTalk session and the
ToolTalk DB server is never contacted.  If TT_FILE scoping had been
used, the second example would NOT have updated the session attribute
in the pattern.

If ToolTalk had no bugs, then setting the scope of a pattern
(via tt_pattern_scope_add) and setting the session and/or file of a
pattern (via tt_pattern_session_add and/or tt_pattern_file_add) would
be all you needed to do and the pattern scopes would match the message
scopes as described above.  However, because of a bug in ToolTalk,
if you do not explicitly join a file, the above scopes will only match
messages that are scoped to both the file and the session of tt_open
the pattern was registered under.  This means that if you do not make
an explicit call to tt_file_join, TT_FILE and TT_BOTH effectively act like
TT_FILE_IN_SESSION.

The reason this occurs is because of how the ToolTalk DB server is used.
When a message is scoped to TT_FILE or TT_BOTH, the ToolTalk client library
that is sending the message (this is where the tt_message_send call was made)
contacts the TT DB server and asks for a list of ToolTalk sessions that
have registered interest in the file the message is scoped to.  The
client library can then send the message to each ToolTalk session in the
list.  When a ToolTalk session receives the message from the sending client,
it can then match the message to patterns that have been registered with
the ToolTalk session and send the messages to any clients that have patterns
that match.  The problem is that the ToolTalk session that a pattern is
registered on is not stored on the ToolTalk DB server until a tt_file_join
call is made, not when an actual pattern is registered.

The reason this is a bug is because when a tt_file_join call is made, this
implicitly does a tt_pattern_file_add to every pattern that has already
been registered and effectively re-registers the patterns.  This means
that there is no way to create several different patterns in one ToolTalk
proc that all scope to different files.  For example, if I make the
following calls:

	tt_open();

	Tt_pattern pat1 = tt_create_pattern();
	tt_pattern_scope_add(pat1, TT_FILE);
	tt_pattern_register(pat1);
	tt_file_join(file1);

	Tt_pattern pat2 = tt_create_pattern();
	tt_pattern_scope_add(pat2, TT_FILE);
	tt_pattern_register(pat2);
	tt_file_join(file2);

	Tt_pattern pat3 = tt_create_pattern();
	tt_pattern_scope_add(pat3, TT_FILE);
	tt_pattern_register(pat3);
	tt_file_join(file3);

Pattern pat1 will actually be scoped to 3 different files (file1, file2,
and file3).  Pattern pat2 will be scoped to 2 files (file2 and file3), and
pattern pat3 will be scoped to just file3.  I can't use just
tt_pattern_file_add to set individual files on individual patterns,
because a tt_pattern_file_add doesn't cause the pattern's ToolTalk session
to be stored in the database.  Only a tt_file_join call will do that.  This
bug will be fixed in a future release of ToolTalk.

Some may ask, if you fix that bug, how will I scope to the union of
TT_FILE_IN_SESSION scope and TT_SESSION scope with one pattern?  Currently,
if I use TT_BOTH on a pattern, register the pattern, and do NOT call
tt_file_join, it effectively provides that ability.

The answer is, when the bug is fixed you can still scope to the union
of TT_FILE_IN_SESSION and TT_SESSION by adding both scopes to the
same pattern:

	tt_open();

	Tt_pattern pat = tt_create_pattern();
	tt_pattern_scope_add(pat, TT_FILE_IN_SESSION);
	tt_pattern_scope_add(pat, TT_SESSION);
	tt_pattern_file_add(pat, file);
	tt_pattern_session_add(pat, tt_default_session());
	tt_pattern_register(pat);

This is the way you should implement the union of the scopes.  When the
file scoping bug is fixed, just adding the scope TT_BOTH will have a
different behavior than it does right now.  However, adding TT_BOTH
and then calling tt_file_join after registering the pattern will have
exactly the same behavior as it does now.

File-based Scoping in Messages
------------------------------
Messages have the same types of file-based scoping mechanisms as patterns:

	TT_FILE - The message is scoped to all clients that have registered
		interest in a file.

	TT_BOTH - The message is scoped to all clients that have registered
		interest in the message's session and/or file.

	TT_FILE_IN_SESSION - The message is scoped to all clients that
		have registered in interest in both the message's file
		and session.

	TT_SESSION + tt_message_file_set() - I've listed this as
		file-based scoping mechanism because of the call to
		tt_message_file_set.  This will scope the message to
		every client that has registered interest in the message's
		session.  When the message is received by a client whose
		pattern matches, the receiving client can get the file
		name by calling tt_message_file.

The bugs that applied to file-scoped patterns do NOT apply to messages.
When a message is TT_FILE or TT_BOTH scoped, the ToolTalk client library
will check the database server for all sessions that have clients that
joined the file and send the message to all of the interested ToolTalk
sessions.  The ToolTalk sessions will then match the messages to the
appropriate clients.  NO explicit call to tt_file_join is required.

In the case of a TT_FILE_IN_SESSION scoped message or a TT_SESSION scoped
message that has a file set in it (via tt_message_file_set), the database
server is not contacted and the message is only sent to clients that are
scoped to the message's session.
__________________________________________
\_Mark Soloway (mark.soloway@Eng.Sun.COM)_\
/_Distributed Systems Services (ToolTalk)_/
\__SunSoft (A Sun Microsystems Company)___\