👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

Linux 2.6 - man page for instrument (linux section 3erl)

instrument(3erl)		     Erlang Module Definition			 instrument(3erl)

NAME
       instrument - Analysis and Utility Functions for Instrumentation

DESCRIPTION
       The  module  instrument contains support for studying the resource usage in an Erlang run-
       time system. Currently, only the allocation of memory can be studied.

   Note:
       Note that this whole module is experimental, and the representations used as well  as  the
       functionality is likely to change in the future.

       The instrument module interface was slightly changed in Erlang/OTP R9C.

       To  start  an Erlang runtime system with instrumentation, use the +Mi* set of command-line
       arguments to the erl command (see the erts_alloc(3erl) and erl(1) man pages).

       The basic object of study in the case of memory allocation is a memory allocation  map.	A
       memory allocation map contains a list of descriptors for each allocated memory block. Cur-
       rently, a descriptor is a 4-tuple

	       {TypeNo, Address, Size, PidDesc}

       where TypeNo is the memory block type number, Address is its place in memory, and Size  is
       its  size,  in  bytes. PidDesc is either a tuple {X,Y,Z} identifying the process which was
       executing when the block was allocated, or undefined if no process was executing. The  pid
       tuple {X,Y,Z} can be transformed into a real pid by usage of the c:pid/3 function.

       Various details about memory allocation:

       Memory  blocks  are  allocated both on the heap segment and on other memory segments. This
       can cause the instrumentation functionality to report  very  large  holes.  Currently  the
       instrumentation functionality doesn't provide any support for distinguishing between holes
       between memory segments, and holes between allocated blocks inside  memory  segments.  The
       current	size  of  the process cannot be obtained from within Erlang, but can be seen with
       one of the system statistics tools, e.g., ps or top . The Solaris utility pmap can be use-
       ful. It reports currently mapped memory segments.

       Overhead  for  instrumentation:	When  the  emulator has been started with the "+Mim true"
       flag, each block is preceded by a 24 bytes large header on a 32-bit machine and a 48 bytes
       large  header on a 64-bit machine. When the emulator has been started with the "+Mis true"
       flag, each block is preceded by an 8 bytes large header. These are the header  sizes  used
       by  the	Erlang	5.3/OTP R9C emulator. Other versions of the emulator may use other header
       sizes. The function block_header_size/1 can be used for retrieving the  header  size  used
       for  a  specific memory allocation map. The time overhead for managing the instrumentation
       data is small.

       Sizes presented by the instrumentation  functionality  are  (by	the  emulator)	requested
       sizes, i.e. neither instrumentation headers nor headers used by allocators are included.

EXPORTS
       allocator_descr(MemoryData, TypeNo) -> AllocDescr | invalid_type | "unknown"

	      Types  MemoryData = {term(), AllocList}
		     AllocList = [Desc]
		     Desc = {int(), int(), int(), PidDesc}
		     PidDesc = {int(), int(), int()} | undefined
		     TypeNo = int()
		     AllocDescr = atom() | string()

	      Returns  the  allocator  description of the allocator that manages memory blocks of
	      type number TypeNo used in MemoryData . Valid TypeNo s are in the range returned by
	      type_no_range/1  on  this  specific  memory allocation map. If TypeNo is an invalid
	      integer, invalid_type is returned.

       block_header_size(MemoryData) -> int()

	      Types  MemoryData = {term(), AllocList}
		     AllocList = [Desc]
		     Desc = {int(), int(), int(), PidDesc}
		     PidDesc = {int(), int(), int()} | undefined

	      Returns the memory block header size used by the emulator that generated the memory
	      allocation map. The block header size may differ between different emulators.

       class_descr(MemoryData, TypeNo) -> ClassDescr | invalid_type | "unknown"

	      Types  MemoryData = {term(), AllocList}
		     AllocList = [Desc]
		     Desc = {int(), int(), int(), PidDesc}
		     PidDesc = {int(), int(), int()} | undefined
		     TypeNo = int()
		     ClassDescr = atom() | string()

	      Returns the class description of the class that the type number TypeNo used in Mem-
	      oryData belongs to. Valid TypeNo s are in the range returned by type_no_range/1  on
	      this  specific memory allocation map. If TypeNo is an invalid integer, invalid_type
	      is returned.

       descr(MemoryData) -> DescrMemoryData

	      Types  MemoryData = {term(), AllocList}
		     AllocList = [Desc]
		     Desc = {int(), int(), int(), PidDesc}
		     PidDesc = {int(), int(), int()} | undefined
		     DescrMemoryData = {term(), DescrAllocList}
		     DescrAllocList = [DescrDesc]
		     DescrDesc = {TypeDescr, int(), int(), DescrPidDesc}
		     TypeDescr = atom() | string()
		     DescrPidDesc = pid() | undefined

	      Returns a memory allocation map where the type numbers (first  element  of  Desc	)
	      have  been  replaced by type descriptions, and pid tuples (fourth element of Desc )
	      have been replaced by real pids.

       holes(MemoryData) -> ok

	      Types  MemoryData = {term(), AllocList}
		     AllocList = [Desc]
		     Desc = {int(), int(), int(), PidDesc}
		     PidDesc = {int(), int(), int()} | undefined

	      Prints out the size of each hole (i.e., the space between allocated blocks) on  the
	      terminal.  NOTE: Really large holes are probably holes between memory segments. The
	      memory allocation map has to be sorted (see sort/1 ).

       mem_limits(MemoryData) -> {Low, High}

	      Types  MemoryData = {term(), AllocList}
		     AllocList = [Desc]
		     Desc = {int(), int(), int(), PidDesc}
		     PidDesc = {int(), int(), int()} | undefined
		     Low = High = int()

	      Returns a tuple {Low, High} indicating the lowest and  highest  address  used.  The
	      memory allocation map has to be sorted (see sort/1 ).

       memory_data() -> MemoryData | false

	      Types  MemoryData = {term(), AllocList}
		     AllocList = [Desc]
		     Desc = {int(), int(), int(), PidDesc}
		     PidDesc = {int(), int(), int()} | undefined

	      Returns  MemoryData  (a the memory allocation map) if the emulator has been started
	      with the " +Mim true  "  command-line  argument;	otherwise,  false  .  NOTE:  mem-
	      ory_data/0  blocks  execution  of  other processes while the data is collected. The
	      time it takes to collect the data can be substantial.

       memory_status(StatusType) -> [StatusInfo] | false

	      Types  StatusType = total | allocators | classes | types
		     StatusInfo = {About, [Info]}
		     About = atom()
		     Info = {InfoName, Current, MaxSinceLast, MaxEver}
		     InfoName = sizes|blocks
		     Current = int()
		     MaxSinceLast = int()
		     MaxEver = int()

	      Returns a list of StatusInfo if the emulator has been started with the " +Mis  true
	      " or " +Mim true " command-line argument; otherwise, false .

	      See the read_memory_status/1 function for a description of the StatusInfo term.

       read_memory_data(File) -> MemoryData | {error, Reason}

	      Types  File = string()
		     MemoryData = {term(), AllocList}
		     AllocList = [Desc]
		     Desc = {int(), int(), int(), PidDesc}
		     PidDesc = {int(), int(), int()} | undefined

	      Reads  a	memory	allocation  map  from  the  file File and returns it. The file is
	      assumed to have been created by store_memory_data/1 . The error codes are the  same
	      as for file:consult/1 .

       read_memory_status(File) -> MemoryStatus | {error, Reason}

	      Types  File = string()
		     MemoryStatus = [{StatusType, [StatusInfo]}]
		     StatusType = total | allocators | classes | types
		     StatusInfo = {About, [Info]}
		     About = atom()
		     Info = {InfoName, Current, MaxSinceLast, MaxEver}
		     InfoName = sizes|blocks
		     Current = int()
		     MaxSinceLast = int()
		     MaxEver = int()

	      Reads  memory  allocation  status  from  the  file File and returns it. The file is
	      assumed to have been created by store_memory_status/1 . The  error  codes  are  the
	      same as for file:consult/1 .

	      When  StatusType	is  allocators	,  About is the allocator that the information is
	      about. When StatusType is types , About is the memory block type that the  informa-
	      tion  is	about.	Memory block types are not described other than by their name and
	      may vary between emulators. When StatusType is classes , About is the memory  block
	      type  class  that information is presented about. Memory block types are classified
	      after their use. Currently the following classes exist:

		process_data :
		  Erlang process specific data.

		binary_data :
		  Erlang binaries.

		atom_data :
		  Erlang atoms.

		code_data :
		  Erlang code.

		system_data :
		  Other data used by the system

	      When InfoName is sizes , Current , MaxSinceLast , and  MaxEver  are,  respectively,
	      current  size, maximum size since last call to store_memory_status/1 or memory_sta-
	      tus/1 with the specific StatusType ,  and  maximum  size	since  the  emulator  was
	      started.	When  InfoName	is  blocks  ,  Current	, MaxSinceLast , and MaxEver are,
	      respectively, current number of blocks, maximum number of blocks since last call to
	      store_memory_status/1 or memory_status/1 with the specific StatusType , and maximum
	      number of blocks since the emulator was started.

	      NOTE: A memory block  is	accounted  for	at  "the  first  level"  allocator.  E.g.
	      fix_alloc allocates its memory pools via ll_alloc . When a fix_alloc block is allo-
	      cated, neither the block nor the pool in which it resides are accounted for as mem-
	      ory allocated via ll_alloc even though it is.

       sort(MemoryData) -> MemoryData

	      Types  MemoryData = {term(), AllocList}
		     AllocList = [Desc]
		     Desc = {int(), int(), int(), PidDesc}
		     PidDesc = {int(), int(), int()} | undefined

	      Sorts a memory allocation map so that the addresses are in ascending order.

       store_memory_data(File) -> true|false

	      Types  File = string()

	      Stores  the  current  memory  allocation map on the file File . Returns true if the
	      emulator has been started with the " +Mim true " command-line argument, and the map
	      was  successfuly	stored;  otherwise, false . The contents of the file can later be
	      read using read_memory_data/1 . NOTE: store_memory_data/0 blocks execution of other
	      processes while the data is collected. The time it takes to collect the data can be
	      substantial.

       store_memory_status(File) -> true|false

	      Types  File = string()

	      Stores the current memory status on the file File . Returns true	if  the  emulator
	      has  been  started with the " +Mis true ", or " +Mim true " command-line arguments,
	      and the data was successfuly stored; otherwise, false . The contents  of	the  file
	      can later be read using read_memory_status/1 .

       sum_blocks(MemoryData) -> int()

	      Types  MemoryData = {term(), AllocList}
		     AllocList = [Desc]
		     Desc = {int(), int(), int(), PidDesc}
		     PidDesc = {int(), int(), int()} | undefined

	      Returns the total size of the memory blocks in the list.

       type_descr(MemoryData, TypeNo) -> TypeDescr | invalid_type

	      Types  MemoryData = {term(), AllocList}
		     AllocList = [Desc]
		     Desc = {int(), int(), int(), PidDesc}
		     PidDesc = {int(), int(), int()} | undefined
		     TypeNo = int()
		     TypeDescr = atom() | string()

	      Returns  the  type description of a type number used in MemoryData . Valid TypeNo s
	      are in the range returned by type_no_range/1 on  this  specific  memory  allocation
	      map. If TypeNo is an invalid integer, invalid_type is returned.

       type_no_range(MemoryData) -> {Min, Max}

	      Types  MemoryData = {term(), AllocList}
		     AllocList = [Desc]
		     Desc = {int(), int(), int(), PidDesc}
		     PidDesc = {int(), int(), int()} | undefined
		     Min = int()
		     Max = int()

	      Returns  the  memory  block  type number range used in MemoryData . When the memory
	      allocation map was generated by an Erlang 5.3/OTP R9C or newer emulator, all  inte-
	      gers T that satisfy Min <= T <= Max are valid type numbers. When the memory alloca-
	      tion map was generated by a pre Erlang 5.3/OTP R9C emulator, all	integers  in  the
	      range are not valid type numbers.

SEE ALSO
       erts_alloc(3erl) , erl(1)

Ericsson AB				  tools 2.6.6.3 			 instrument(3erl)


All times are GMT -4. The time now is 11:06 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password





Not a Forum Member?
Forgot Password?