// dump the heap to given path.

int HeapDumper::dump(const char* path) {

  {- -------------------------------------------
  (1) (assert)
      ---------------------------------------- -}

      assert(path != NULL && strlen(path) > 0, "path missing");

  {- -------------------------------------------
  (1) (トレース出力)
      ---------------------------------------- -}

      // print message in interactive case
      if (print_to_tty()) {
        tty->print_cr("Dumping heap to %s ...", path);
        timer()->start();
      }

  {- -------------------------------------------
  (1) DumpWriter を使って, 引数で指定された出力先ファイルを開く.
      もし失敗したら (トレース出力) を出して, ここでリターン.
      ---------------------------------------- -}

      // create the dump writer. If the file can be opened then bail
      DumpWriter writer(path);
      if (!writer.is_open()) {
        set_error(writer.error());
        if (print_to_tty()) {
          tty->print_cr("Unable to create %s: %s", path,
            (error() != NULL) ? error() : "reason unknown");
        }
        return -1;
      }

  {- -------------------------------------------
  (1) VM_HeapDumper::doit() でダンプ出力を実行する.
      (もし, この関数を実行しているのが VM_thread であれば, 直接 VM_HeapDumper::doit() を実行する.
       そうでなければ, VMThread::execute() 経由で実行する.)
      ---------------------------------------- -}

      // generate the dump
      VM_HeapDumper dumper(&writer, _gc_before_heap_dump, _oome);
      if (Thread::current()->is_VM_thread()) {
        assert(SafepointSynchronize::is_at_safepoint(), "Expected to be called at a safepoint");
        dumper.doit();
      } else {
        VMThread::execute(&dumper);
      }

  {- -------------------------------------------
  (1) 出力が終わったので, 出力先ファイルを閉じる.
      ---------------------------------------- -}

      // close dump file and record any error that the writer may have encountered
      writer.close();
      set_error(writer.error());

  {- -------------------------------------------
  (1) (トレース出力)
      ---------------------------------------- -}

      // print message in interactive case
      if (print_to_tty()) {
        timer()->stop();
        if (error() == NULL) {
          char msg[256];
          sprintf(msg, "Heap dump file created [%s bytes in %3.3f secs]",
            os::jlong_format_specifier(), timer()->seconds());
          tty->print_cr(msg, writer.bytes_written());
        } else {
          tty->print_cr("Dump file is incomplete: %s", writer.error());
        }
      }

  {- -------------------------------------------
  (1) 結果をリターン
      ---------------------------------------- -}

      return (writer.error() == NULL) ? 0 : -1;
    }