Package com.wolfram.jlink.util

Class 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/SystemFiles/Links/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/SystemFiles/Links/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.
    -kernelhost ip address, when using TCPIP (like the -LinkHost option). -kernelopts extra info like MLDontInteract (like the -LinkOptions option). 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)
      -timestamps        (include timestamps in output)
    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.util.LinkSnooper -kernelname 'd:/math60/mathkernel.exe'");

   // C
   MLINK ml = MLOpenString(env, "javaw com.wolfram.jlink.util.LinkSnooper -kernelname 'd:/math60/mathkernel.exe'", &err);

   // C#  (.NET/Link)
   IKernelLink ml = MathLinkFactory.CreateKernelLink("javaw com.wolfram.jlink.util.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.util.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

      Constructors 
      Constructor Description
      LinkSnooper​(java.lang.String[] argv)  
      LinkSnooper​(java.lang.String[] argv, java.io.PrintStream pstrm)  

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      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, clone, countStackFrames, currentThread, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, onSpinWait, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, suspend, toString, yield

      • Methods inherited from class java.lang.Object

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