Sending and Receiving Messages in the Same Process

Normally, the receiver deletes the message when it has completed the requested operation. However, the ToolTalk service uses the same message ID for both the receiver and the requestor. When sending and receiving messages in the same process, these features cause the message underneath the requestor to be deleted as well.

One workaround is to put a refcount on the message. To do this, use the tt_message_user[_set]() function.

Another workaround is to destroy the message in the receiver only if the sender is not the current procid; for example:

Tt_callback_action
my_pattern_callback(Tt_message m, Tt_pattern p)
{
	/* normal message processing goes here */

	if (0!=strcmp(tt_message_sender(m),tt_default_procid()) {
		tt_message_destroy(m);
	}
	return TT_CALLBACK_PROCESSED;
}

Sending and Receiving Messages in a Networked Environment

You can use the ToolTalk service in a networked environment; for example, you can start a tool on a different machine or join a session that is running on a different machine. To do so, invoke a ttsession with either the -c or -p option.

The -c option will invoke the named program and place the right session id in its TT_SESSION environment variable. For example, the command
ttsession -c dtterm

defines TT_SESSION in that cmdtool and any ToolTalk client you run with the environment variable $TT_SESSION set to its value will join the session owned by this ttsession.

The -p option prints the session id to standard output. ttsession then forks into the background to run that session.

To join the session, an application must either pass the session id to tt_default_session_set or place the session id in the environment variable TT_SESSION before it calls the tt_open function. tt_open will check the environment variable TT_SESSION and join the indicated session (if it has a value).

Unregistering from the ToolTalk Service

When you want to stop interacting with the ToolTalk service and other ToolTalk session participants, you must unregister your process before your application exits.

	/*
	 * Before leaving, allow ToolTalk to clean up.
	 */
	tt_close();

	exit(0);
}

tt_close returns Tt_status and closes the current default procid.

Using ToolTalk in a Multi-Threaded Environment

This section describes how to use ToolTalk in a multi-threaded environment.

Initialization

Using the ToolTalk library with multi-threaded clients requires an initialization call like the following call:

tt_feature_required(TT_FEATURE_MULTITHREADED);

The call must be invoked before any other ToolTalk call is made. Attempts to call tt_feature_required(TT_FEATURE_MULTITHREADED)after other ToolTalk API calls have been made will result in a TT_ERR_TOOLATE error.

Libraries and other reusable modules that use ToolTalk might want to query the ToolTalk library to determine if the invoking application has enabled the multi-thread feature of ToolTalk. The tt_feature_enabled() API call was added for this purpose. Top-level applications rarely need to use tt_feature_enabled() since the application would know if it had already done the initialization.

ToolTalk procids and sessions

When a ToolTalk client calls tt_open() or tt_session_join(), the new procid or session is the default for the thread (and not the entire process as would be the for a non-multi-threaded ToolTalk client). A thread's default procid and session, before any calls to tt_open() or tt_session_join() are made, are initially the same as the defaults for the creator of the thread. In addition to changing the defaults with tt_open() or tt_session_join(), tt_thread_procid_set() and tt_thread_session_set() can be used to switch to other defaults created previously. The default procid and session values can be retrieved using tt_thread_procid() and tt_thread_session(). The thread-specific procid and session values are managed through the use of thread-specific storage. If no value has yet been created in the thread, the default value for the entire ToolTalk process is the fallback value.

Note - It is possible for the values returned by tt_default_procid() and tt_thread_procid() (and similarly, tt_default_session() and tt_thread_session()) to be different at any given time for some thread. This is so because tt_default_procid_set() and tt_default_session_set() do not affect the default values for a thread. They only affect the default values for the entire ToolTalk process.

Using threads with ToolTalk enabled applications is a natural implementation technique for programs that switch procids and sessions. These programs might, at some point, want to easily determine which ToolTalk procid is associated with a ToolTalk session. This was difficult to do in previous versions of ToolTalk. tt_procid_session() has been provided to accomplish this. Although tt_procid_session()does not depend on threads, it is useful for applications that use threads with ToolTalk.

ToolTalk storage

tt_mark() and tt_release()affect storage allocated on a per-thread basis, not a per-process basis. Therefore, one thread cannot use tt_release() to release storage that was marked by another thread using tt_mark().

Common Problems

Using one thread to send a message and another to process a message is a common technique. However, use care when destroying a message with tt_message_destroy() when another thread might be examining and processing the message contents. This typically results in a program crash when the receiving thread tries to access storage that was freed by another thread. This is the same as managing non-ToolTalk storage in multi-threaded applications, but easier to do using the ToolTalk API.


7. Participating in ToolTalk Sessions Setting Up to Receive Messages