flash.sampler - 詳細資料 Adobe ActionScript® 3 (AS3 ) API 參考

隨附於 Adobe Flash Builder 的剖析代理程式 (Profiling Agent) 會使用本套件，您也可以使用本套件自訂剖析代理程式或建構自己的記憶體測試。使用 startSampling() 方法與 Flash Player 除錯版本 9.0.115.0 或更新版本，收集記憶體使用情形樣本。使用 getSamples() 方法擷取記憶體使用情形的樣本。樣本會顯示執行中程式記憶體使用情形的明顯區隔。然後，使用 flash.sampler 套件中的其它方法分析記憶體使用情形的資訊。

注意：如果您要建立自己的自訂剖析代理程式，請在 mm.cfg 檔案中設定 PreloadSwf 屬性，預先載入代理 SWF 檔：

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

每個預先載入的代理 SWF 檔都具有各自的安全性網域，並且會從剖析的主要 SWF 檔的明確安全執行程序內執行。若要執行 flash.sampler 套件的方法，代理 SWF 檔必須位於 localTrusted 檔案路徑 (請參閱安全中心)。

公用方法

	函數		定義自
		clearSamples():void 清除目前的 Sample 物件集合。	flash.sampler
		getGetterInvocationCount(obj:Object, qname:QName):Number 傳回執行 get 函數的次數。	flash.sampler
		getInvocationCount(obj:Object, qname:QName):Number 傳回執行方法的次數。	flash.sampler
		getLexicalScopes(obj:Function):Array 公開「函數」的語彙範圍，讓設定可以看到擷取的範圍物件 (包括具有範圍的啟動物件)，如同被「函數」實體所保留一般。	flash.sampler
		getMasterString(str:String):String 傳回字串相依的主字串，或者如果此字串未與其他字串相依則為 null。	flash.sampler
		getMemberNames(o:Object, instanceNames:Boolean = false):Object 傳回包含指定物件之所有成員 (包括私有成員) 的物件。	flash.sampler
		getSampleCount():Number 傳回所收集的樣本數目。	flash.sampler
		getSamples():Object 從最後一個取樣工作階段中傳回記憶體用量 Sample 實體的物件。	flash.sampler
		getSavedThis(obj:Function):Object 從 Method 結束項傳回儲存的 "this"，這通常您不能從 AS 看到。	flash.sampler
		getSetterInvocationCount(obj:Object, qname:QName):Number 傳回執行 set 函數的次數。	flash.sampler
		getSize(o:*):Number 搭配 Flash Player 9.0.115.0 或更新的除錯程式版本使用時，傳回指定的物件在記憶體中的大小。	flash.sampler
		isGetterSetter(obj:Object, qname:QName):Boolean 檢查屬性是否由 get/set 函數所定義。	flash.sampler
		pauseSampling():void 暫時停止取樣程序。	flash.sampler
		sampleInternalAllocs(b:Boolean):void 通知取樣程式是否應該從 Flash Player 建立內部配置的 NewObjectSamples。	flash.sampler
		setSamplerCallback(f:Function):void 替取樣程式設定回呼函數 – 當取樣串流快要耗盡時，會呼叫這個函數。	flash.sampler
		startSampling():void 開始收集記憶體用量 Sample 物件的程序。	flash.sampler
		stopSampling():void 結束收集記憶體用量 Sample 物件的程序，並釋放專門用於取樣程序的資源。	flash.sampler

函數詳細資訊

clearSamples

()

函數

public function clearSamples():void

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9.0.115.0

清除目前的 Sample 物件集合。在呼叫 getSamples() 及重複執行 Sample 物件之後，通常會呼叫這個方法。僅限 Flash Player 除錯程式版本。

相關 API 元素

getSamples()

getGetterInvocationCount

()

函數

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

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9.0.115.0

傳回執行 get 函數的次數。使用 isGetterSetter() 驗證您具備 get/set 函數，然後再使用 getGetterInvocationCount()。僅限 Flash Player 除錯程式版本。

參數

	`obj:Object` — 方法實體或類別。

	`qname:QName` — 如果 qname 為 `undefined`，則會傳回建構函數的循環數目。

傳回值

Number — 執行 get 方法的次數。

相關 API 元素

isGetterSetter()
getInvocationCount()

getInvocationCount

()

函數

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

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9.0.115.0

傳回執行方法的次數。如果參數 obj 為 Class，而且參數 qname 為 undefined，這個方法會傳回建構函數的循環數目。僅限 Flash Player 除錯程式版本。

參數

	`obj:Object` — 方法實體或類別。無法使用方法實體時，類別可用來取得實體函數的叫用次數。如果 `obj` 為 `undefined`，會傳回 `qname` 所命名的 package-scoped 函數的數目。

	`qname:QName` — 如果 qname 為 `undefined`，則會傳回建構函數的循環數目。

傳回值

Number — 執行方法的次數。

範例 ( 如何使用本範例 )

 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) { }
      
    }
}

getLexicalScopes

()

函數

public function getLexicalScopes(obj:Function):Array

公開「函數」的語彙範圍，讓設定可以看到擷取的範圍物件 (包括具有範圍的啟動物件)，如同被「函數」實體所保留一般。

參數

obj:Function — 函數

傳回值

Array — 包含所有語彙範圍元素的陣列。

getMasterString

()

函數

public function getMasterString(str:String):String

語言版本:

ActionScript 3.0

傳回字串相依的主字串，或者如果此字串未與其他字串相依則為 null。例如，如果您呼叫 String.substr()，實際上通常會為了效率，將傳回的字串實作成到原始字串中的指標。在正常使用下，這是使用者看不到的實作細節；不過，當使用設定工具來分析程式的記憶體使用量時，可能會令人混淆，因為該字串耗用的記憶體，可能會比該字串值所需的記憶體還少。此外，也可能會將字串單獨保留在記憶體中，因為該字串是其他字串的主字串。getMasterString() 允許設定工具對使用者顯示字串相依項的精確圖表。

參數

str:String — 字串

傳回值

String — 傳入字串相依的字串，或者如果傳入字串未與其他字串相依則為 null。

getMemberNames

()

函數

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

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9.0.115.0

傳回包含指定物件之所有成員 (包括私有成員) 的物件。然後您可以重複執行傳回的物件以查看所有值。這個方法與 flash.utils.describeType() 方法相似，但它可讓您查看私有成員並略過建立 XML 物件的中間步驟。僅限 Flash Player 除錯程式版本。

參數

	`o:Object` — 要分析的物件。

	`instanceNames:Boolean` (default = `false`) — 如果物件為 Class 而且 instanceNames 為 true，報告實體名稱時會將 o 當做類別實體 (而非類別成員名稱)。

傳回值

Object — 物件，必須使用 for each..in 迴圈重複執行，以擷取每個屬性的 QNames。

相關 API 元素

flash.utils.describeType()
for each..in

範例 ( 如何使用本範例 )

下列範例會使用 getMemberNames() 方法來分析物件，並顯示其成員的 buttonMode、filters 和 dispatchEvent 屬性。若要使用記憶體設定，您必須安裝 Flash Player 除錯程式版本 9.0.115.0 或更新版本。

 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

()

函數

public function getSampleCount():Number

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9.0.115.0

傳回所收集的樣本數目。僅限 Flash Player 除錯程式版本。

傳回值

Number — Sample 實體的迴圈指標。

相關 API 元素

flash.sampler.Sample

getSamples

()

函數

public function getSamples():Object

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9.0.115.0

從最後一個取樣工作階段中傳回記憶體用量 Sample 實體的物件。僅限 Flash Player 除錯程式版本。

傳回值

Object — Sample 實體的迴圈指標。

相關 API 元素

flash.sampler.Sample

getSavedThis

()

函數

public function getSavedThis(obj:Function):Object

從 Method 結束項傳回儲存的 "this"，這通常您不能從 AS 看到。

參數

obj:Function — MethodClosure 實體

傳回值

Object — 是 MethodClosure 的 "this" 之物件

getSetterInvocationCount

()

函數

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

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9.0.115.0

傳回執行 set 函數的次數。使用 isGetterSetter() 驗證您具備 get/set 函數，然後再使用 getSetterInvocationCount()。僅限 Flash Player 除錯程式版本。

參數

	`obj:Object` — 方法實體或類別。

	`qname:QName` — 如果 qname 為 `undefined`，則會傳回建構函數的循環數目。

傳回值

Number — 執行 set 方法的次數。

相關 API 元素

isGetterSetter()
getInvocationCount()

getSize

()

函數

public function getSize(o:*):Number

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9.0.115.0

搭配 Flash Player 9.0.115.0 或更新的除錯程式版本使用時，傳回指定的物件在記憶體中的大小。如果不是搭配除錯程式版本的 Flash Player 使用，這個方法會傳回 0。

參數

o:* — 要進行記憶體用量分析的物件。

傳回值

Number — 指定的物件使用的記憶體位元組數。

範例 ( 如何使用本範例 )

下列範例使用 startSampling() 和 pauseSampling 來收集 Sample 物件。此範例接著重複執行 Sample 物件以取得 id 值和大小。在呼叫 System.gc() 以停止目前程序之後，範例會比較 deletedObjectSample 物件與原始 id 值並顯示其大小。若要使用記憶體設定，您必須安裝 Flash Player 除錯程式版本 9.0.115.0 或更新版本。

 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

()

函數

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

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9.0.115.0

檢查屬性是否由 get/set 函數所定義。如果您想要在屬性的 get/set 函數上使用 getInvocationCount()，請先呼叫 isGetterSetter()，檢查它是否為 get/set 函數，然後使用 getSetterInvocationCount 或 getGetterInvocationCount 取得個別計數。僅限 Flash Player 除錯程式版本。

參數

	`obj:Object` — 方法實體或類別。

	`qname:QName` — 如果 qname 為 `undefined`，則會傳回建構函數的循環數目。

傳回值

Boolean — Boolean 值，表示屬性是否 (true 為是，false 為否) 由 get/set 函數所定義。

範例 ( 如何使用本範例 )

 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

()

函數

public function pauseSampling():void

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9.0.115.0

暫時停止取樣程序。使用 startSampling() 重新啟動取樣程序。僅限 Flash Player 除錯程式版本。

相關 API 元素

startSampling()

sampleInternalAllocs

()

函數

public function sampleInternalAllocs(b:Boolean):void

語言版本:

ActionScript 3.0

通知取樣程式是否應該從 Flash Player 建立內部配置的 NewObjectSamples。如果這是 true，則每個配置均會產生 NewObjectSample。這些內部配置不會有類型或是參考到 Object。這會讓 ActionScript 堆疊觸發配置的追蹤。預設為 false，這只會收集 ActionScript 物件的配置。

參數

b:Boolean

setSamplerCallback

()

函數

public function setSamplerCallback(f:Function):void

語言版本:

ActionScript 3.0

替取樣程式設定回呼函數 – 當取樣串流快要耗盡時，會呼叫這個函數。應該在填入取樣緩衝區之前，先使用這個函數處理取樣。在呼叫回呼之前先呼叫 pauseSampling，而且在回呼執行之後，將會呼叫 startSampling。

參數

f:Function

startSampling

()

函數

public function startSampling():void

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9.0.115.0

開始收集記憶體用量 Sample 物件的程序。僅限 Flash Player 除錯程式版本。

相關 API 元素

Sample 類別

範例 ( 如何使用本範例 )

下列範例會起始取樣程序並重複執行所收集的物件。若要使用記憶體分析工具，必須有 Flash Player 除錯程式版本 9.0.115.0 或更新版本。

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

()

函數

public function stopSampling():void

語言版本:

ActionScript 3.0

執行階段版本:

AIR 1.0, Flash Player 9.0.115.0

結束收集記憶體用量 Sample 物件的程序，並釋放專門用於取樣程序的資源。您可以使用 startSampling() 開始取樣程序。僅限 Flash Player 除錯程式版本。

相關 API 元素

Sample 類別

法律聲明 | 線上隱私權政策

套件 flash.sampler

類別 x

clearSamples

getGetterInvocationCount

getInvocationCount

getLexicalScopes

getMasterString

getMemberNames

getSampleCount

getSamples

getSavedThis

getSetterInvocationCount

getSize

isGetterSetter

pauseSampling

sampleInternalAllocs

setSamplerCallback

startSampling

stopSampling