com.hdcookbook.grin.util
Class Profile

java.lang.Object
  com.hdcookbook.grin.util.Profile

public class Profile
extends java.lang.Object

Profiling support. This is enabled or disabled by setting the static variable Debug.PROFILE to true or false. When profiling is enabled, parts of the GRIN framework will give you profiling data, and you might wish to profile parts of your xlet's code as well. As of this writing, the direct draw animation manager collects profiling data for key parts of the animation loop.

Each profile call is associated with a byte "thread ID." This is meant to provide a lightweight mechanism to seperate out execution in different threads. The programmer must pass in a byte constant for this; we don't try to lookup the current thread with any automated means, because doing so would be time-consuming. We expect the developer to know what happens on what thread, and we expect that a typical xlet will have a very small number of well-defined threads that are of interest for profiling. Thread IDs from 0xf8 through 0xff are reserved for the cookbook tools, and are declared as constants in this class; beyond that, it's up to the developer to manage the namespace of thread IDs.

Usage:

     private static byte[] PROFILE_TIMER_1;
     static {
          if (Debug.PROFILE) {
              PROFILE_TIMER_1 = Profile.makeProfileTimer("My animation");
          }
      }
      <...>
      public void myMethod() {
          int token;
          if (Profile.PROFILE) {
              Profile.initProfiler(2008, "127.0.0.1");
              token = Profile.startTimer(PROFILE_TIMER_1, 
                                         Profile.TID_ANIMATION);
          }
          doTheThingIWantMeasured();
          if (Profile.PROFILE) {
              Profile.stopTimer(token);
              Profile.doneProfiling();
          }
      }
 

Author:

Jaya

Field Summary

static byte	MESSAGE
static byte	TID_ANIMATION Constant for the thread ID of the GRIN animation thread.
static byte	TID_SETUP Constant for the thread ID of the GRIN setup thread.
static byte	TIMER_START
static byte	TIMER_STOP

Method Summary

static void	doneProfiling() Indicates profiling is over, releases the network resources.
static void	initProfiler(int port, java.lang.String host) Initializes this class with the network address of the remote computer where profiling is done.
static void	initTokenStart(int tokenStart) Initialize the starting point of counting for tokens.
static byte[]	makeMessage(java.lang.String message) Allocates buffer and returns UTF-8 bytes for a debug message packet.
static byte[]	makeProfileTimer(java.lang.String description) Allocates buffer and returns UTF-8 bytes for the string representing profile information.
static void	sendMessage(byte[] buf) Send a message packet
static int	startTimer(byte[] startBuf, byte threadID) Signals starting the timer on the remote computer.
static void	stopTimer(int tk) Signals stopping the timer on the remote computer.

Methods inherited from class java.lang.Object

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

Field Detail

TIMER_START

public static final byte TIMER_START

See Also:

Constant Field Values

TIMER_STOP

public static final byte TIMER_STOP

See Also:

Constant Field Values

MESSAGE

public static final byte MESSAGE

See Also:

Constant Field Values

TID_ANIMATION

public static final byte TID_ANIMATION

Constant for the thread ID of the GRIN animation thread.

See Also:

startTimer(byte[], byte), Constant Field Values

TID_SETUP

public static final byte TID_SETUP

Constant for the thread ID of the GRIN setup thread.

See Also:

startTimer(byte[], byte), Constant Field Values

Method Detail

initProfiler

public static void initProfiler(int port,
                                java.lang.String host)

Initializes this class with the network address of the remote computer where profiling is done. This is a NOP if Debug.PROFILE is false.

Parameters:

port - The UDP port on which the remote computer is waiting for data

host - The hostname or the IP address of the remote computer

initTokenStart

public static void initTokenStart(int tokenStart)

Initialize the starting point of counting for tokens. This usually isn't needed, but it makes it possible for one xlet's tokens to start from where a previous xlet's ended. This lets you use the profiler to do things like time xlet startup time.

makeProfileTimer

public static byte[] makeProfileTimer(java.lang.String description)

Allocates buffer and returns UTF-8 bytes for the string representing profile information. This method is meant to be called by the application during class loading: Usage:

     private static byte[] PROFILE_TIMER_1;
     static {
          if (Debug.PROFILE) {
              PROFILE_TIMER_1 = Profile.makeProfileTimer("my animation");
          }
     }
 

Parameters:

description - of the task that is being profiled.

Returns:

A UTF-8 encoded byte array representing the description.

makeMessage

public static byte[] makeMessage(java.lang.String message)

Allocates buffer and returns UTF-8 bytes for a debug message packet. The first byte of the result is added by the profiling framework, and should not be modified. Any other bytes can be, e.g. to insert numeric result data without generating heap objects. Usage:

     private static byte[] PROFILE_MESSAGE_1;
     static {
          if (Debug.PROFILE) {
              PROFILE_MESSAGE_1 
                  = Profile.makeMessage("count now X");
          }
     }

     <...>
           
        if (Debug.PROFILE) {
             PROFILE_MESSAGE_1[PROFILE_MESSAGE_1.length - 1]
                 = (byte) count;
             Profile.sendMessage(PROFILE_MESSAGE_1);
        }
 

Parameters:

message - the message

Returns:

A UTF-8 encoded byte array for the message

doneProfiling

public static void doneProfiling()

Indicates profiling is over, releases the network resources.

startTimer

public static int startTimer(byte[] startBuf,
                             byte threadID)

Signals starting the timer on the remote computer.

Parameters:

startBuf - Buffer holding the description of the block of code that is time. This byte array should be obtained from makeProfileTimer().

threadID - Identifier of the "thread" this execution occurs on. See the class comments about "thread," and why it's a byte.

Returns:

Returns the token for the task that is timed

See Also:

makeProfileTimer(String), Profile

stopTimer

public static void stopTimer(int tk)

Signals stopping the timer on the remote computer.

Parameters:

tk - Token for the task that is done.

sendMessage

public static void sendMessage(byte[] buf)

Send a message packet

Parameters:

buf - Buffer holding the message. This byte array should be obtained from makeMessage().

See Also:

makeMessage(String), Profile