startuptime: move code to profile.{c,h} + doc

It's a better place to put it. Also slightly documented and reformatted, but
not changed.

4 files changed, 134 insertions, 93 deletions

diff --git a/src/nvim/macros.h b/src/nvim/macros.h
index bff19f17dd..f8fd6ac6a2 100644
--- a/src/nvim/macros.h
+++ b/src/nvim/macros.h
@@ -116,12 +116,6 @@
 #  define mch_open_rw(n, f)     os_open((n), (f), 0)
 #endif
 
-#ifdef STARTUPTIME
-# define TIME_MSG(s) { if (time_fd != NULL) time_msg(s, NULL); }
-#else
-# define TIME_MSG(s)
-#endif
-
 # define REPLACE_NORMAL(s) (((s) & REPLACE_FLAG) && !((s) & VREPLACE_FLAG))
 
 # define UTF_COMPOSINGLIKE(p1, p2)  utf_composinglike((p1), (p2))
diff --git a/src/nvim/main.c b/src/nvim/main.c
index 344baa6b53..442e19dae0 100644
--- a/src/nvim/main.c
+++ b/src/nvim/main.c
@@ -45,6 +45,7 @@
 #include "nvim/option.h"
 #include "nvim/os_unix.h"
 #include "nvim/path.h"
+#include "nvim/profile.h"
 #include "nvim/quickfix.h"
 #include "nvim/screen.h"
 #include "nvim/strings.h"
@@ -2248,90 +2249,3 @@ static void check_swap_exists_action(void)
 #endif
 
 #endif
-
-#if defined(STARTUPTIME) || defined(PROTO)
-
-static struct timeval prev_timeval;
-
-
-/*
- * Save the previous time before doing something that could nest.
- * set "*tv_rel" to the time elapsed so far.
- */
-void time_push(void *tv_rel, void *tv_start)
-{
-  *((struct timeval *)tv_rel) = prev_timeval;
-  gettimeofday(&prev_timeval, NULL);
-  ((struct timeval *)tv_rel)->tv_usec = prev_timeval.tv_usec
-    - ((struct timeval *)tv_rel)->tv_usec;
-  ((struct timeval *)tv_rel)->tv_sec = prev_timeval.tv_sec
-    - ((struct timeval *)tv_rel)->tv_sec;
-  if (((struct timeval *)tv_rel)->tv_usec < 0) {
-    ((struct timeval *)tv_rel)->tv_usec += 1000000;
-    --((struct timeval *)tv_rel)->tv_sec;
-  }
-  *(struct timeval *)tv_start = prev_timeval;
-}
-
-/*
- * Compute the previous time after doing something that could nest.
- * Subtract "*tp" from prev_timeval;
- * Note: The arguments are (void *) to avoid trouble with systems that don't
- * have struct timeval.
- */
-void 
-time_pop (
-    void *tp        /* actually (struct timeval *) */
-)
-{
-  prev_timeval.tv_usec -= ((struct timeval *)tp)->tv_usec;
-  prev_timeval.tv_sec -= ((struct timeval *)tp)->tv_sec;
-  if (prev_timeval.tv_usec < 0) {
-    prev_timeval.tv_usec += 1000000;
-    --prev_timeval.tv_sec;
-  }
-}
-
-static void time_diff(struct timeval *then, struct timeval *now)
-{
-  long usec;
-  long msec;
-
-  usec = now->tv_usec - then->tv_usec;
-  msec = (now->tv_sec - then->tv_sec) * 1000L + usec / 1000L,
-       usec = usec % 1000L;
-  fprintf(time_fd, "%03ld.%03ld", msec, usec >= 0 ? usec : usec + 1000L);
-}
-
-void 
-time_msg (
-    char *mesg,
-    void *tv_start      /* only for do_source: start time; actually
-                                 (struct timeval *) */
-)
-{
-  static struct timeval start;
-  struct timeval now;
-
-  if (time_fd != NULL) {
-    if (strstr(mesg, "STARTING") != NULL) {
-      gettimeofday(&start, NULL);
-      prev_timeval = start;
-      fprintf(time_fd, "\n\ntimes in msec\n");
-      fprintf(time_fd, " clock   self+sourced   self:  sourced script\n");
-      fprintf(time_fd, " clock   elapsed:              other lines\n\n");
-    }
-    gettimeofday(&now, NULL);
-    time_diff(&start, &now);
-    if (((struct timeval *)tv_start) != NULL) {
-      fprintf(time_fd, "  ");
-      time_diff(((struct timeval *)tv_start), &now);
-    }
-    fprintf(time_fd, "  ");
-    time_diff(&prev_timeval, &now);
-    prev_timeval = now;
-    fprintf(time_fd, ": %s\n", mesg);
-  }
-}
-
-#endif
diff --git a/src/nvim/profile.c b/src/nvim/profile.c
index 6a77d42205..0643dce559 100644
--- a/src/nvim/profile.c
+++ b/src/nvim/profile.c
@@ -6,6 +6,13 @@
 #include "nvim/os/time.h"
 #include "nvim/func_attr.h"
 
+#if defined(STARTUPTIME) || defined(PROTO)
+#include <string.h>    // for strstr
+#include <sys/time.h>  // for struct timeval
+
+#include "nvim/vim.h"  // for the global `time_fd`
+#endif
+
 #ifdef INCLUDE_GENERATED_DECLARATIONS
 # include "profile.c.generated.h"
 #endif
@@ -182,3 +189,121 @@ int profile_cmp(proftime_T tm1, proftime_T tm2) FUNC_ATTR_CONST
 {
   return sgn64((int64_t)(tm2 - tm1));
 }
+
+#if defined(STARTUPTIME) || defined(PROTO)
+
+static struct timeval prev_timeval;
+
+/// time_push - save the previous time before doing something that could nest
+///
+/// After calling this function, the static global `prev_timeval` will
+/// contain the current time.
+///
+/// @param[out] tv_rel to the time elapsed so far
+/// @param[out] tv_start the current time
+void time_push(void *tv_rel, void *tv_start)
+{
+  // save the time elapsed so far into tv_rel
+  *((struct timeval *)tv_rel) = prev_timeval;
+
+  // set prev_timeval to the current time
+  gettimeofday(&prev_timeval, NULL);
+
+  // subtract the previous time from the current time, store it in tv_rel
+  ((struct timeval *)tv_rel)->tv_usec = prev_timeval.tv_usec
+    - ((struct timeval *)tv_rel)->tv_usec;
+  ((struct timeval *)tv_rel)->tv_sec = prev_timeval.tv_sec
+    - ((struct timeval *)tv_rel)->tv_sec;
+
+  // correct usec overflow
+  if (((struct timeval *)tv_rel)->tv_usec < 0) {
+    ((struct timeval *)tv_rel)->tv_usec += 1000000;
+    --((struct timeval *)tv_rel)->tv_sec;
+  }
+
+  // set tv_start to now
+  *(struct timeval *)tv_start = prev_timeval;
+}
+
+/// time_pop - compute the prev time after doing something that could nest
+///
+/// Subtracts `*tp` from the static global `prev_timeval`.
+///
+/// Note: The arguments are (void *) to avoid trouble with systems that don't
+/// have struct timeval.
+///
+/// @param tp actually `struct timeval *`
+void time_pop(const void *tp)
+{
+  // subtract `tp` from `prev_timeval`
+  prev_timeval.tv_usec -= ((struct timeval *)tp)->tv_usec;
+  prev_timeval.tv_sec -= ((struct timeval *)tp)->tv_sec;
+
+  // correct usec oveflow
+  if (prev_timeval.tv_usec < 0) {
+    prev_timeval.tv_usec += 1000000;
+    --prev_timeval.tv_sec;
+  }
+}
+
+/// time_diff - print the difference between `then` and `now`
+///
+/// the format is "msec.usec".
+static void time_diff(const struct timeval *then, const struct timeval *now)
+{
+  // convert timeval (sec/usec) to (msec,usec)
+  long usec = now->tv_usec - then->tv_usec;
+  long msec = (now->tv_sec - then->tv_sec) * 1000L + usec / 1000L;
+  usec %= 1000L;
+
+  fprintf(time_fd, "%03ld.%03ld", msec, usec >= 0 ? usec : usec + 1000L);
+}
+
+/// time_msg - print out timing info
+///
+/// when `mesg` contains the text "STARTING", special information is
+/// printed.
+///
+/// @param mesg the message to display next to the timing information
+/// @param tv_start only for do_source: start time; actually (struct timeval *)
+void time_msg(const char *mesg, const void *tv_start)
+{
+  static struct timeval start;
+  struct timeval now;
+
+  if (time_fd == NULL) {
+    return;
+  }
+
+  // if the message contains STARTING, print some extra information and
+  // initialize a few variables
+  if (strstr(mesg, "STARTING") != NULL) {
+    // intialize the `start` static variable
+    gettimeofday(&start, NULL);
+    prev_timeval = start;
+
+    fprintf(time_fd, "\n\ntimes in msec\n");
+    fprintf(time_fd, " clock   self+sourced   self:  sourced script\n");
+    fprintf(time_fd, " clock   elapsed:              other lines\n\n");
+  }
+
+  // print out the difference between `start` (init earlier) and `now`
+  gettimeofday(&now, NULL);
+  time_diff(&start, &now);
+
+  // if `tv_start` was supplied, print the diff between `tv_start` and `now`
+  if (((struct timeval *)tv_start) != NULL) {
+    fprintf(time_fd, "  ");
+    time_diff(((struct timeval *)tv_start), &now);
+  }
+
+  // print the difference between the global `prev_timeval` and `now`
+  fprintf(time_fd, "  ");
+  time_diff(&prev_timeval, &now);
+
+  // set the global `prev_timeval` to `now` and print the message
+  prev_timeval = now;
+  fprintf(time_fd, ": %s\n", mesg);
+}
+
+#endif
diff --git a/src/nvim/profile.h b/src/nvim/profile.h
index 26d1ebe3a2..bca83ba90d 100644
--- a/src/nvim/profile.h
+++ b/src/nvim/profile.h
@@ -6,6 +6,14 @@
 
 typedef uint64_t proftime_T;
 
+#ifdef STARTUPTIME
+#define TIME_MSG(s) do { \
+  if (time_fd != NULL) time_msg(s, NULL); \
+} while (0)
+#else
+#define TIME_MSG(s)
+#endif
+
 #ifdef INCLUDE_GENERATED_DECLARATIONS
 # include "profile.h.generated.h"
 #endif