Adobe® Flex® 4 Language Reference
Hide Packages and Classes List |  Packages  |  Classes  |  Index  |  Appendixes
 
Package flash.sampler 

This package is used by the profiling agent distributed with Adobe Flash Builder, and is provided for your use for customizing the profiling agent or building your own memory tests. Use the startSampling() method and the Flash Player debugger version 9.0.115.0 or later, to collect memory usage samples. Then use the getSamples() method to retrieve memory usage samples. The samples reveal the memory usage of distinct intervals of a running application. Then use the other methods in the flash.sampler package to analyze the memory usage information.

Note: If you create your own custom profiling agent, preload the agent SWF file by setting the PreloadSwf property in the mm.cfg file:

PreloadSwf=C:/Documents and Settings/username/testingagent.swf?aparam=asetting

Each preloaded agent SWF file has its own security domain and runs in a distinct security sandbox from the main SWF file being profiled. To run the methods of the flash.sampler package, the agent SWF file must be in a localTrusted file path (see the Flash Player 9 Security white paper).

Public Methods
 FunctionDefined By
  
Clears the current set of Sample objects.
flash.sampler
  
Returns the number of times a get function was executed.
flash.sampler
  
Returns the number of times a method was executed.
flash.sampler
  
getMemberNames(o:Object, instanceNames:Boolean = false):Object
Returns an object containing all members of a specified object, including private members.
flash.sampler
  
Returns the number of samples collected.
flash.sampler
  
Returns an object of memory usage Sample instances from the last sampling session.
flash.sampler
  
Returns the number of times a set function was executed.
flash.sampler
  
Returns the size in memory of a specified object when used with the Flash Player 9.0.115.0 or later debugger version.
flash.sampler
  
Checks to see if a property is defined by a get/set function.
flash.sampler
  
Stops the sampling process momentarily.
flash.sampler
  
Begins the process of collecting memory usage Sample objects.
flash.sampler
  
Ends the process of collecting memory usage Sample objects and frees resources dedicated to the sampling process.
flash.sampler
Function detail

clearSamples

()function
public function clearSamples():void

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9.0.115.0

Clears the current set of Sample objects. This method is usually called after calling getSamples() and iterating over the Sample objects. For Flash Player debugger version only.

See also

getGetterInvocationCount

()function 
public function getGetterInvocationCount(obj:Object, qname:QName):Number

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9.0.115.0

Returns the number of times a get function was executed. Use isGetterSetter() to verify that you have a get/set function before you use getGetterInvocationCount(). For Flash Player debugger version only.

Parameters

obj:Object — A method instance or a class.
 
qname:QName — If qname is undefined return the number of iterations of the constructor function.

Returns
Number — The number of times a get method was executed.

See also

getInvocationCount

()function 
public function getInvocationCount(obj:Object, qname:QName):Number

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9.0.115.0

Returns the number of times a method was executed. If the parameter obj is a Class and the parameter qname is undefined then this method returns the number of iterations of the constructor function. For Flash Player debugger version only.

Parameters

obj:Object — A method instance or a class. A class can be used to get the invocation count of instance functions when a method instance isn't available. If obj is undefined, this method returns the count of the package-scoped function named by qname.
 
qname:QName — If qname is undefined return the number of iterations of the constructor function.

Returns
Number — The number of times a method was executed.

Example  ( How to use this example )

 package 
{
  public function exec3() {}

  import flash.sampler.*;
  import flash.system.*;
  import flash.display.Sprite;
  import flash.utils.*;
  public class getInvocationCountTest extends Sprite
    {
      public function getInvocationCountTest()
    {
      for(var i:int=0;i<10;i++)
        exec();
      for(var i:int=0;i<10;i++)
        exec2();
      for(var i:int=0;i<10;i++)
        exec3();

      // get exec QName
      var execName:QName;
          var name:QName;
      var fooName:QName;
      for each(name in getMemberNames(this)) {
          if(name.localName == "exec")
          execName = name;
          if(name.localName == "foo")
          fooName = name;
      }

      var exec2Name:QName;
      for each(name in getMemberNames(getInvocationCountTest)) {
          if(name.localName == "exec2")
          exec2Name = name;
      }

      // execute get/set
      foo = "bar";

      trace(isGetterSetter(this, fooName));
      trace(getSetterInvocationCount(this, fooName) == 1);
      trace(getGetterInvocationCount(this, fooName) == 0);

      foo;
      
      trace(getSetterInvocationCount(getInvocationCountTest, fooName) == 1);
      trace(getGetterInvocationCount(getInvocationCountTest, fooName) == 1);

      trace(getInvocationCount(this, execName) == 10);
      trace(getInvocationCount(getInvocationCountTest, execName) == 10);
      trace(getInvocationCount(getInvocationCountTest, exec2Name) == 10);
      trace(getInvocationCount(getInvocationCountTest, undefined) == 1);
    
      getTimer();
      getTimer();

      trace(getInvocationCount(undefined, new QName("", "trace")) == 9);
      trace(getInvocationCount(undefined, new QName("flash.utils", "getTimer")) == 2);
      trace(getInvocationCount(undefined, new QName("", "exec3")) == 10);

    }

      private function exec():void {}
      private static function exec2():void {}

      private function get foo():String { return "fo"; }
      private function set foo(s:String) { }
      
    }
}

getMemberNames

()function 
public function getMemberNames(o:Object, instanceNames:Boolean = false):Object

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9.0.115.0

Returns an object containing all members of a specified object, including private members. You can then iterate over the returned object to see all values. This method is similar to the flash.utils.describeType() method but also allows you to see private members and skips the intermediate step of creating an XML object. For Flash Player debugger version only.

Parameters

o:Object — The object to analyze.
 
instanceNames:Boolean (default = false) — If object is a Class and instanceNames is true report the instance names as if o was an instance of class instead of the class's member names.

Returns
Object — An Object that you must iterate over with a for each..in loop to retrieve the QNames for each property.

See also


Example  ( How to use this example )

The following example uses the getMemberNames() method to analyze an object and display the buttonMode, filters and dispatchEvent properties of its members, To use the memory profiler, you need to have Flash Player debugger version 9.0.115.0 or later installed.
 package 
{
  import flash.sampler.*;
  import flash.system.*;
  import flash.display.Sprite;
  public class getMemberNamesTest extends Sprite
    {
      public function getMemberNamesTest()
    {
      var name_iter = getMemberNames(this);
      var o={};
      for each(var name:QName in name_iter) {
        o[name.localName] = "got it";
      }

      name_iter = getMemberNames(this);
      var count=0;
      for(var dum in name_iter) {
        count++;
      }
      trace(count == 1);

      // my member
      trace("buttonMode" in o);
      // inherited member
      trace("filters" in o);
      // inherited function
      trace("dispatchEvent" in o);

      var name_iter = getMemberNames(getMemberNamesTest, true);
      var o={};
      for each(var name:QName in name_iter) {
        o[name.localName] = "got it";
      }

      // my member
      trace("buttonMode" in o);
      // inherited member
      trace("filters" in o);
      // inherited function
      trace("dispatchEvent" in o);

    }
    }
}

getSampleCount

()function 
public function getSampleCount():Number

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9.0.115.0

Returns the number of samples collected. For Flash Player debugger version only.

Returns
Number — An iterator of Sample instances.

See also

getSamples

()function 
public function getSamples():Object

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9.0.115.0

Returns an object of memory usage Sample instances from the last sampling session. For Flash Player debugger version only.

Returns
Object — An iterator of Sample instances.

See also

getSetterInvocationCount

()function 
public function getSetterInvocationCount(obj:Object, qname:QName):Number

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9.0.115.0

Returns the number of times a set function was executed. Use isGetterSetter() to verify that you have a get/set function before you use getSetterInvocationCount(). For Flash Player debugger version only.

Parameters

obj:Object — A method instance or a class.
 
qname:QName — If qname is undefined return the number of iterations of the constructor function.

Returns
Number — The number of times a set method was executed.

See also

getSize

()function 
public function getSize(o:*):Number

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9.0.115.0

Returns the size in memory of a specified object when used with the Flash Player 9.0.115.0 or later debugger version. If used with a Flash Player that is not the debugger version, this method returns 0.

Parameters

o:* — The object to analyze for memory usage.

Returns
Number — The byte count of memory used by the specified object.

Example  ( How to use this example )

The following example uses startSampling() and pauseSampling to collect Sample objects. The example then iterates over the Sample objects for id values and sizes. After calling System.gc() to stop the current process, the example compares the deletedObjectSample objects to the original id values and displays their size. To use the memory profiler, you need to have Flash Player debugger version 9.0.115.0 or later installed.
 package {
  import flash.sampler.*;
  import flash.system.*;
  import flash.display.Sprite;
  import flash.utils.Dictionary;
  public class deletedObjectSize extends Sprite {
    public function deletedObjectSize() {

      startSampling();
      var obj = {};
      pauseSampling();

      var id:Number;
      var sampleIter = getSamples();
      for each(var s:Sample in sampleIter) {
    id = s.id;
      }
      
      sampleIter = getSamples();
      var count=0;
      for(var dum in sampleIter) {
    count++;
      }
      trace(count == 1);

      var size:Number = getSize(obj);
      obj = undefined;

      startSampling();

      // force DRC
      for(var i:int=0;i<1000;i++)
    new Object();
      
      System.gc();

      pauseSampling();
      
      var sampleIter = getSamples();
      for each(var s:Sample in sampleIter) {
    //    trace(s);
    if(s is DeleteObjectSample && s.id == id) {
      trace(s.size == size);
    }      
      }       

    }
  }
}

isGetterSetter

()function 
public function isGetterSetter(obj:Object, qname:QName):Boolean

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9.0.115.0

Checks to see if a property is defined by a get/set function. If you want to use getInvocationCount() on a get/set function for a property, first call isGetterSetter() to check to see if it is a get/set function, and then use either getSetterInvocationCount or getGetterInvocationCount to get the respective counts. For Flash Player debugger version only.

Parameters

obj:Object — A method instance or a class.
 
qname:QName — If qname is undefined return the number of iterations of the constructor function.

Returns
Boolean — A Boolean value indicating if the property is defined by a get/set function (true) or not (false).

See also


Example  ( How to use this example )

 package 
{
  public function exec3() {}

  import flash.sampler.*;
  import flash.system.*;
  import flash.display.Sprite;
  import flash.utils.*;
  public class getInvocationCountTest extends Sprite
    {
      public function getInvocationCountTest()
    {
      for(var i:int=0;i<10;i++)
        exec();
      for(var i:int=0;i<10;i++)
        exec2();
      for(var i:int=0;i<10;i++)
        exec3();

      // get exec QName
      var execName:QName;
          var name:QName;
      var fooName:QName;
      for each(name in getMemberNames(this)) {
          if(name.localName == "exec")
          execName = name;
          if(name.localName == "foo")
          fooName = name;
      }

      var exec2Name:QName;
      for each(name in getMemberNames(getInvocationCountTest)) {
          if(name.localName == "exec2")
          exec2Name = name;
      }

      // execute get/set
      foo = "bar";

      trace(isGetterSetter(this, fooName));
      trace(getSetterInvocationCount(this, fooName) == 1);
      trace(getGetterInvocationCount(this, fooName) == 0);

      foo;
      
      trace(getSetterInvocationCount(getInvocationCountTest, fooName) == 1);
      trace(getGetterInvocationCount(getInvocationCountTest, fooName) == 1);

      trace(getInvocationCount(this, execName) == 10);
      trace(getInvocationCount(getInvocationCountTest, execName) == 10);
      trace(getInvocationCount(getInvocationCountTest, exec2Name) == 10);
      trace(getInvocationCount(getInvocationCountTest, undefined) == 1);
    
      getTimer();
      getTimer();

      trace(getInvocationCount(undefined, new QName("", "trace")) == 9);
      trace(getInvocationCount(undefined, new QName("flash.utils", "getTimer")) == 2);
      trace(getInvocationCount(undefined, new QName("", "exec3")) == 10);

    }

      private function exec():void {}
      private static function exec2():void {}

      private function get foo():String { return "fo"; }
      private function set foo(s:String) { }
      
    }
}

pauseSampling

()function 
public function pauseSampling():void

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9.0.115.0

Stops the sampling process momentarily. Restart the sampling process using startSampling(). For Flash Player debugger version only.

See also

startSampling

()function 
public function startSampling():void

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9.0.115.0

Begins the process of collecting memory usage Sample objects. For Flash Player debugger version only.

See also


Example  ( How to use this example )

The following example initiates the sampling process and iterates over the collected objects. To use the memory profiler, you need to have Flash Player debugger version 9.0.115.0 or later.
package 
{
    import flash.sampler.*
    import flash.system.*
    import flash.display.Sprite
    public class startSampling extends Sprite
    {
        public function startSampling()
        {
            flash.sampler.startSampling();
            for(var i:int=0;i<1000;i++)
                new Object()
            trace(getSampleCount() > 0)
        }
    }
}

stopSampling

()function 
public function stopSampling():void

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9.0.115.0

Ends the process of collecting memory usage Sample objects and frees resources dedicated to the sampling process. You start the sampling process with startSampling(). For Flash Player debugger version only.

See also