com.wolfram.jlink.util
Class LinkSnooper

java.lang.Object
  java.lang.Thread
      com.wolfram.jlink.util.LinkSnooper

All Implemented Interfaces:

java.lang.Runnable

public class LinkSnooper
extends java.lang.Thread

LinkSnooper is a program that sits between a front end and kernel (or any two MathLink programs) and displays all traffic that moves across the link between them. It has a special feature that allows it to also monitor the "service link" and "preemptive link" between a Mathematica version 6.x notebook front end and kernel.

LinkSnooper uses the J/Link Console Window to display its output. This window is set to store a very large number of lines of output in its scrollable buffer, and writing to the window can slow down noticeably as the buffer fills with output. To speed things up, use the Clear button to delete output you no longer care about. You can also temporarily stop capture by unchecking the System.out radio button.

Using LinkSnooper to monitor front end-kernel connections

1) Make sure JLink.jar is on the CLASSPATH. If you do not have it on the CLASSPATH, you can use a -cp option in the java command lines below, but beware of quoting issues.

2) In the FrontEnd, go to the Kernel/Kernel Configuration Options dialog and Add a new connection. Call it LinkSnooper. Click the Advanced Options radio button and in the Arguments to MLOpen field, put something like this:

   (Windows)
   -LinkMode Launch -LinkName "javaw com.wolfram.jlink.util.LinkSnooper -kernelname 'd:/math60/mathkernel'"

   (Windows with a classpath spec)
   -LinkMode Launch -LinkName "javaw -cp \"c:/path/to/JLink.jar\" com.wolfram.jlink.util.LinkSnooper -kernelname 'd:/math60/mathkernel'"

   (Unix)
   -LinkMode Launch -LinkName "java com.wolfram.jlink.util.LinkSnooper -kernelname 'math -mathlink'"

   (Unix with a classpath spec)
   -LinkMode Launch -LinkName "java -cp /usr/local/Wolfram/Mathematica/6.0/AddOns/JLink/JLink.jar com.wolfram.jlink.util.LinkSnooper -kernelname 'math -mathlink'"

   (OS/X)
   -LinkMode Launch -LinkName "java com.wolfram.jlink.util.LinkSnooper -kernelname '/Applications/Mathematica\ 6.0.app/Contents/MacOS/MathKernel -mathlink'"

   (OS/X with a classpath spec)
   -LinkMode Launch -LinkName "java -cp /Applications/Mathematica\ 6.0.app/AddOns/JLink/JLink.jar com.wolfram.jlink.util.LinkSnooper -kernelname '/Applications/Mathematica\ 6.0.app/Contents/MacOS/MathKernel -mathlink'" 

You can modify these according to your kernel path and whether you need to supply a full path to the java executable.

If you need to specify other options for the kernel connection, use the following names in the same way that -kernelname is used in the examples above:

      -kernelname  'path/to/kernel' (for a launch)
      -kernelmode  listen, connect, launch
      -kernelprot  SharedMemory, TCPIP, etc. 

The FrontEnd sends a lot of initialization traffic across the link after it launches the kernel. Printing this information can greatly slow the startup process unless you constantly click the Clear button to keep the window contents small. To avoid printing this initialization traffic, you can pass the command-line argument:

      -noinit    (don't print any traffic until the first user input) 

LinkSnooper also supports the following command-line arguments that control its output:

      -logfile filename  (write output to specified log file in addition to window)
      -nowindow          (don't display output window; useful with -logfile option)
 

3) When the FrontEnd launches the kernel, you will see the J/Link Java console window appear. This is where the output goes. On some platforms, when you quit the kernel the console window will stay up until you close the console window, at which point Java will quit.

Using LinkSnooper for other programs

Although LinkSnooper has special features for monitoring front end-to-kernel links, you can use it between any two MathLink programs. The basic idea is that when your program goes to launch the other MathLink program (e.g., a kernel), you launch LinkSnooper instead, passing it the information it needs to launch the target program itself. Thus, LinkSnooper sits between your program and the program it wants to communicate with. Because LinkSnooper is a standalone program, you can use it from any language, for example:

   // Java
   KernelLink ml = MathLinkFactory.createKernelLink("javaw com.wolfram.jlink.LinkSnooper -kernelname 'd:/math60/mathkernel.exe'");
   
   // C
   MLINK ml = MLOpenString(env, "javaw com.wolfram.jlink.LinkSnooper -kernelname 'd:/math60/mathkernel.exe'", &err);
   
   // C#  (.NET/Link)
   IKernelLink ml = MathLinkFactory.CreateKernelLink("javaw com.wolfram.jlink.LinkSnooper -kernelname 'd:/math60/mathkernel.exe'");  

You can also use Listen/Connect modes to manually establish a connection to an already-running kernel. You do this using the -kernelmode and -kernelprot options to LinkSnooper. Note that your program will launch LinkSnooper, and it is LinkSnooper that will do the Listen/Connect with the kernel. Here is an example of this:

   (* In Mathematica: *)
   In[1]:= $ParentLink = LinkCreate["1234"]  (* Open a LinkMode->Listen link *)
   
   // In Java (or C, or C#, etc.)
   KernelLink ml = MathLinkFactory.createKernelLink("javaw com.wolfram.jlink.LinkSnooper -kernelname 1234 -kernelmode connect"); 

You can also use command-line options to control how the names of the two sides of the link are represented in the output. By default, their names are FE and K, so each packet is prefixed with an arrow like this: FE ---> K (or the reverse direction). If you have LinkSnooper working on a link between programs for which the names FE and K are not appropriate, you can alter these names so the output is easier to read. By definition, the "FE side" is the program that launched LinkSnooper (or otherwise connected to it directly). The "kernel side" is the side that LinkSnooper connects to based on the -kernelname, -kernelmode, etc. options described above.

      -feSide      Name    (name of FE-side program to print in output)
      -kernelSide  Name    (name of kernel-side program to print in output)
 

Nested Class Summary

Nested classes/interfaces inherited from class java.lang.Thread

java.lang.Thread.State, java.lang.Thread.UncaughtExceptionHandler

Field Summary

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

LinkSnooper(java.lang.String[] argv)

LinkSnooper(java.lang.String[] argv, java.io.PrintStream pstrm)

Method Summary

void	feMainMessageHandler(int msgType, int ignore)
void	fePreemptiveMessageHandler(int msgType, int ignore)
void	feServiceMessageHandler(int msgType, int ignore)
void	kernelMainMessageHandler(int msgType, int ignore)
void	kernelPreemptiveMessageHandler(int msgType, int ignore)
void	kernelServiceMessageHandler(int msgType, int ignore)
static void	main(java.lang.String[] argv)
void	run()

Methods inherited from class java.lang.Thread

activeCount, checkAccess, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

LinkSnooper

public LinkSnooper(java.lang.String[] argv)
            throws MathLinkException

Throws:

MathLinkException

LinkSnooper

public LinkSnooper(java.lang.String[] argv,
                   java.io.PrintStream pstrm)
            throws MathLinkException

Throws:

MathLinkException

Method Detail

main

public static void main(java.lang.String[] argv)
                 throws MathLinkException

Throws:

MathLinkException

run

public void run()

Specified by:

run in interface java.lang.Runnable

Overrides:

run in class java.lang.Thread

feMainMessageHandler

public void feMainMessageHandler(int msgType,
                                 int ignore)
                          throws MathLinkException

Throws:

MathLinkException

kernelMainMessageHandler

public void kernelMainMessageHandler(int msgType,
                                     int ignore)
                              throws MathLinkException

Throws:

MathLinkException

fePreemptiveMessageHandler

public void fePreemptiveMessageHandler(int msgType,
                                       int ignore)
                                throws MathLinkException

Throws:

MathLinkException

kernelPreemptiveMessageHandler

public void kernelPreemptiveMessageHandler(int msgType,
                                           int ignore)
                                    throws MathLinkException

Throws:

MathLinkException

feServiceMessageHandler

public void feServiceMessageHandler(int msgType,
                                    int ignore)
                             throws MathLinkException

Throws:

MathLinkException

kernelServiceMessageHandler

public void kernelServiceMessageHandler(int msgType,
                                        int ignore)
                                 throws MathLinkException

Throws:

MathLinkException