frameprof - ICE 0.1 API documentation

ICE 0.1 API documentation

# frameprof

Utility script extracting data from ICE frame profiler output.

alias YAMLNode;

  TODO:
  Commands TODO: #. memprof-filter with a particular zone
  #. accumulate: Different merge modes: if multiple instances of the same zone in a "zones" of a parent zone, sum all these instances, (count them as a single "total" zone) or process them separately (current mergeZones behavior) (this changes averages/maximums between frames - i.e. is maximum calculated from a sum of all instances of the subzone in a zone or from each of them separately?) That is: --mergeZones=total vs --mergeZones=separate
  #. Filter frames: Filter frames by start/end time (e.g. all frames between 1s and 5s) filter by frame duration (all frames about 16 ms)
  #, Filter zones: Zone name by regex. So we can get e.g. all occurences of zone X in all frames, but no other zones. Also filter by duration (e.g. ignore all zones below e.g. 1microsec) And maybe by duration percentage? (ignore zones below e.g. 0.5% of parent zone)
  #. Distribution (frames): Distribute frames by duration. Aggregate frame count, time, average time. total/average aliases, like MemProf.
  #. Accumulate all frames into single "frame: (this is similar to usual profiling). This will be complicated with non-identical frames but should be possible. Support various functions - e.g. average, max, min. Max allows us to see occassional lags. Maybe also some "variance" or something, i.e. how much do the results vary.
  #. (Long term) GUI zone browser.
  #. ASCII graph:
  A command would take a sequence of frames, and turn each into a graph like this. So we could e.g. get top worst frames, or filter them in some another way, and get their graphs.
  The graphis would in single text output separated by some pattern (e.g. =================)
  Root zone is the whole frame, 100%, one big rect at the top. Below it, nested zones appear as rectangles starting at their respective times. E.g:

          |                     FRAME- 20 milliseconds                                   |

  | VISUAL SYSTEM UPDATE - 6ms | | OTHER SYSTEMS UPDATES - 10ms | ------------------------------- -------------------------------- We would store the data, then at exit, dump it to a file. A Python (or D) script could process it into above ASCII art.
  This would show every zone instance a separate rectangle.
  We could also create vertical ASCII art - might be better (scrolling)
  Especially important would be looking for "worst" frames - which are caused e.g. by GC fullcollect. #. SVG graph: Same as ASCII graph, but SVG.
  Readability aliases
struct FrameProf;

  Main FrameProf object.

  Contains all profiling functionality. Might be split into multiple classes/functions if needed.

  this(string fileName);

    Construct FrameProf loading profile data from specified file.

  this(ref File file);

    Construct FrameProf loading profile data from specified file object (e.g. stdin).

  @property ref YAMLNode frameProfile();

    Get the memory log loaded from YAML.

  static Node[] topFrames(ref YAMLNode frames, bool delegate(ref Node, ref Node) less, const ulong topCount);

    Get the topCount greatest frames sorted by specified less function.

    Parameters:

    YAMLNode frames | Frames to process.
    bool delegate(ref Node, ref Node) less | Comparison function to sort the frames.
    ulong topCount | Number of frames to get.

    Returns:
    An array of topCount greatest frames.
  static YAMLNode accumulateFrames(ref YAMLNode frames, Flag!("mergeZones") mergeZones);

    Accumulate data from all frames into a single "total" frame.

    Parameters:

    YAMLNode frames | Frames to accumulate
    Flag!("mergeZones") mergeZones | If there are multiple identical child zones in a parent zone, should they be merged into a single "total" zone? (Otherwise, they will be numbered).

    Throws:
    YAMLException if a frame or zone has unexpected format.
Tuple!(T,T)[] parseRanges(T)(string raw);

  Parse a string of ranges in format "a-b,c-d,e".

  Parameters:

  raw | Raw string before parsing.

  Returns:
  Parsed ranges.
  Throws:
  ConvException on a number parsing error. FrameProfCLIException on an invalid range.
void processOption(string arg, void delegate(string, string[]) process);

  Process a command line option (argument starting with --).

  Parameters:

  string arg | Argument to process.
  void delegate(string, string[]) process | Function to process the option. Takes the option and its arguments.

  Throws:
  FrameProfCLIException if arg is not an option, and anything process() throws.
void help();

  Print help information.

class FrameProfCLIException: object.Exception;

  Exception thrown at CLI errors.

struct FrameProfCLI;

  Parses FrameProf CLI commands, composes them into an action to execute, and executes it.

  this(string[] cliArgs);

    Construct a FrameProfCLI with specified command-line arguments and parse them.

  void execute();

    Execute the action specified by command line arguments.

void main(string[] args);

  Program entry point.

Copyright © Ferdinand Majerech 2011. | Page generated by AutoDDoc and Ddoc.