How are memory (byte) ordering issues handled by the ToolTalk service?

The ToolTalk service allows you to place ints, strings, and byte vectors into messages. An XDR routine ensures that these data types are correct for each client. If you have data that is not one of these three data types, you must serialize the data into a byte vector before you place it into a message.

Can I re-use messages?

No. Messages cannot be sent multiple times with different arguments. They must be iteratively created, sent, and then destroyed.

What happens when I destroy a message?

When you destroy a message, you destroy the handle but not the underlying message. The underlying message is destroyed only when ToolTalk is done with it and all the external handles are destroyed. For example, if you destroy a handle to a message immediately after you send it, you will get a new handle when the reply comes back.

However, once you destroy a message, the ToolTalk service will not show it to you again under any circumstances. For example, if you register a pattern to observe a request you send and then destroy the message when your pattern matches it, you will not see the message when it is in state "handled" (that is, when it is a reply).

Can I have more than one handler per message?

No, not currently. If you want multiple processes, you can use notices; or you can use message rejection to force the ToolTalk service to deliver the request to all the possible handlers -- however, each of these handlers must actually perform some kind of operation.

Can I run more than one handler of a given ptype?

Yes, you can run more than one handler of a given ptype. However, the ToolTalk service does not have a concept of load balancing; that is, the ToolTalk service will choose one of the handlers and deliver additional matching messages to the chosen handler only. There are several ways to force the ToolTalk service to deliver messages to other handlers:

1. Use tt_message_reject.

   If a message comes in and a process does not want to handle it because the process is busy, the process can reject the message. The ToolTalk service will then try the next possible handler (and apply the disposition options when it runs out of registered handlers.)

   This method requires the process to be in an event loop; that is, it must call tt_message_receive when the tt_fd is active. However, if the process is in a heavy computational loop, this method fails.

2. Unregister the pattern when busy. For example:

   m = tt_message_receive();
   if (m is the message that causes us to go busy) {
        tt_pattern_unregister(p);
   }

The ToolTalk service will not route matching messages to the process when the pattern is not registered. When you want the process to receive messages again, re-register the pattern.

Note - This method causes a race condition. For example, a second message could be sent and routed to the process in the time between the first tt_message_receive call and the tt_pattern_unregister call.

1. A combination of Methods 1 and 2.

   You can use a combination of the first two techniques in the following manner:

get the message
   unregister the pattern
   loop, calling tt_message_receive until it returns 0; reject
   all the returned messages
   handle the message
   re-register the pattern
   repeat

Note - This method assumes that the process only registers one pattern.

What value is disposition in a message?

Message disposition can override the disposition specified in the static type definition. If the message specifies the handler ptype and the message does not match any of the static signatures, the disposition set in the message will be the one followed. For example, if the disposition in the message is TT_START and the ptype specifies a start-string, an instance will be started.

What are the message status elements?

The ToolTalk service does not use message_status_string. This message component is for use by the applications. The ToolTalk service only sets the message status if a problem occurs with message delivery; otherwise, this message component is set and read in an application-dependent manner.

When should I use tt_free?

libtt maintains an internal storage stack from which you receive data buffers. When you call a ToolTalk API routine, any char * or void * returned points to a copy that you are responsible for freeing.

Use the mark and release functions to free allocated buffers during a sequence of operations. However, the release call frees everything allocated since the corresponding mark call. If you want to store certain data that was returned by the ToolTalk service, make a copy of the data before you do any operations that may free it.

What does the ptype represent?

Ptypes are programmer-defined strings that name tool kinds. (You can roughly translate ptype as process type.) Each ptype can be associated with a set of patterns that describe the messages in which that particular ptype is interested and a string for the ToolTalk service to invoke when an instance of that ptype needs to be started.

The main purpose of ptypes is to allow tools to express interest in messages even when no instance of the tool is actually running in the scope in which the message is sent. If a tool is able to perform a message's requested operation, or wants to be notified when a particular message is sent, it indicates this instruction in its ptype and ToolTalk will start the tool when necessary. Since the ptypes database can also be modified by the system administrator or user, the mechanism allows the site's or user's favorite tool be designated as the tool to handle a particular message.

Why are my new types not recognized?

ttsession reads the types database on start-up, on receipt of a USR1 signal, or when notified by a special ToolTalk message that the types databases have changed. Normally there is no need to manually update a ttsession to reread the types files. However, if you wish to force a running ttsession to reread the types databases, you may do so by sending it the USR2 signal; for example:

kill -USR2 <ttsession pid>

Is ptype information used if a process of that ptype already exists?

The ToolTalk service always looks for one handler and any number of observers for every message. In this case, even though the ToolTalk service finds a handler running, it will still look through the ptypes for any observe patterns that match the message. If a ptype with an observe pattern that matches does exist and there is no process of that ptype currently running, the ToolTalk service will start a new process or queue the message (as specified in the ptype pattern or in the message).

Can the ptype definition be modified to always start an instance (whether or not one is already running)?

No. Messages to a ptype are blocked during start-up until the ptype either replies to the message, or issues a tt_message_accept call. However, the implementation of the ptype can include tt_message_reject for any request it gets that do not have a status of TT_WRN_START_MESSAGE. All requests will then be delivered to (and rejected by) all running instances of the ptype before a new one gets started. This method will be slow if many of these ptypes are running at the same time, or if the message contains a large amount of data. Alternatively, you could use tt_message_accept, which basically unblocks messages to the ptype.

What does tt_ptype_declare do?

When you declare the ptype, your static patterns exist in ttsession memory. When a ptype is registered by an application, the ToolTalk service also checks for otypes that mention the ptype and registers the patterns found in these otypes. To activate the static patterns, your application must call the appropriate join functions.

Note - Multiple declarations by an application of the same ptype are ignored.

What is TT_TOKEN?

When processing message that requires an application to be started, the ToolTalk service sets this environment variable in the child process. When the application starts and performs tt_open, this information is passed back to the ToolTalk service to inform it that the application coming up is the one started or delegated to handle the message.

When are my patterns active?

A pattern must be registered with the session in which it wants to be active. Patterns can be active for more than one file (for a given procid); the file part of the pattern will match any of the listed files.

Note - Contexts are not scopes. A pattern that is joined to contexts but not joined to any file or session cannot match any message.

Must I register patterns to get replies?

No. You do not need to register patterns to get replies. However, if you do register a pattern that matches a reply, the reply will come through your event loop twice: once because it matched a pattern, and again because it is a reply.

How can I observe requests?

Observers can observe requests if the pattern matches and the message is not point-to-point (that is, TT_HANDLER). If your observer pattern is not matching any requests, you can run ttsession in trace mode to find out why.

How do I match to attribute values in static patterns?

The ToolTalk static pattern (that is, types database) mechanism does not allow you to match patterns by attribute values. You can match by file scope or argument vtype but you cannot by match by the particular filename or by argument value.

Note - This restriction also applies for matching on contexts in static patterns.

Why am I unable to wildcard a pattern for TT_HANDLER?

You cannot wildcard patterns for TT_HANDLER-addressed messages because these messages are not pattern matched.

Can I set a pattern to watch for any file scoped message?

No. Not specifying a file name when you use file scoping is virtually the same as specifying that you want to match to file-scoped messages about every file in the universe.

Note - A session attribute may be set on a file-scoped pattern to emulate file-in-session scoping; however, a tt_session_join call will not update the session attribute of a pattern that is scoped as TT_FILE.

Is file scope in static patterns the same as file_in_session scope?

No, these scopes have different purposes.

For example, assume all sessions currently have the same static patterns and at least one pattern P that will match a message M (which you will be sending). No session has any clients that have registered interest in the file foo.bar.

You are connected to session A and issue a file-scoped message M for file foo.bar. Since no client of any session has previously expressed any interest in this file, session A is the only file that will get the message. (The message will match against static pattern P in session A.) Once the ptype is started, the pattern actually becomes scoped to file (within that session) and session A will honor all the promises.

However, if all sessions do not have the same static patterns, the results are different. For example, session B could have an extra pattern P' that is file-scoped and that should match message M. When message M is sent in session A, the dbserver will not send the message to session B if no client of session B has previously expressed interest in the file foo.bar. However, if a client of session B has previously expressed interest in the file foo.bar, then the dbserver would know that at least one client in that session was interested in the file foo.bar and would send also the message to session B.