[elpa] externals/m-buffer c0946dbe6c 085/115: Documentations updates.

[ELPA Syncer]

branch: externals/m-buffer
commit c0946dbe6cc65e42d87b725fb232921455d619a5
Author: Phillip Lord <phillip.lord@newcastle.ac.uk>
Commit: Phillip Lord <phillip.lord@newcastle.ac.uk>

    Documentations updates.
---
 Makefile              |   1 -
 m-buffer-benchmark.el | 145 ++++++++++++++++++++++++++++++++++++++++++++++++++
 m-buffer-doc.org      |   7 +++
 m-buffer-macro.el     |   9 ++--
 4 files changed, 157 insertions(+), 5 deletions(-)

diff --git a/Makefile b/Makefile
index 9b1fc0b0fb..940857d288 100644
--- a/Makefile
+++ b/Makefile
@@ -9,7 +9,6 @@ install:
 test: install
        cask exec ert-runner
 
-
 clean:
        find . -name "m-buffer*org" -not -name "m-buffer-doc.org" \
           -exec rm {} \;
diff --git a/m-buffer-benchmark.el b/m-buffer-benchmark.el
new file mode 100644
index 0000000000..2d84f93d11
--- /dev/null
+++ b/m-buffer-benchmark.el
@@ -0,0 +1,145 @@
+;;; Benchmarking:
+
+;; This file is not meant a emacs package, but for benchmarking m-buffer.
+;; To hide Emacs' there are lots of places where m-buffer saves, changes and 
then
+;; restores this global state. One obvious question is what impact does this 
have
+;; on performance. We check this here.
+
+;; ** Evaluation
+
+;;    The results of running these forms are "pre-evaluated", because this file
+;;    forms part of the lentic documentation for m-buffer. We could evaluate
+;;    these at export time but, by default, this form of evaluation is blocked.
+;;    Moreover, it can be quite slow which would be less than ideal with
+;;    lentic-server.
+
+;;    To evaluate on the local machine use `org-babel-execute-buffer', probably
+;;    after setting `org-confirm-babel-evaluate' to nil.
+
+;; ** Support
+
+;;    Build a nice simple bench macro.
+
+;; #+begin_src emacs-lisp
+(defmacro bench
+    (&rest body)
+  `(format "%e"
+           (car
+            (benchmark-run-compiled
+             1000000
+             (progn
+               ,@body)))))
+;; #+end_src
+
+;; #+RESULTS:
+;; : bench
+
+;; ** How Long does it take to change current-buffer
+
+;; *** Entering and Restoring
+
+;;     There are lots of places where we set the current buffer, do something, 
then
+;;     get the result again, so understanding how long this takes is important.
+;;     So, how long does it take to set and restore the current buffer.
+
+;;     It's quite a bit slower -- about an order of magnitude.
+
+;; **** Implementation
+
+;;     We get the `current-buffer' and `point'. In the first case, we also do
+;;     this inside a `with-current-buffer'.
+
+;; #+begin_src emacs-lisp
+(bench
+ (with-current-buffer
+     (current-buffer)
+   (point)))
+;; #+end_src
+
+;; #+RESULTS:
+;; : 3.371566e-02
+
+
+;; #+begin_src emacs-lisp
+(bench
+ (current-buffer)
+ (point))
+;; #+end_src
+
+;; #+RESULTS:
+;; : 2.120534e-03
+
+
+;; *** Does buffer context help
+
+;;    Is `with-current-buffer' quicker if we are already in the current-buffer?
+;;    This is interesting to know because if it is, grouping several commands
+;;    that operate on a single would run much faster.
+
+;;    We test this by entering having two `with-current-buffer' calls which do
+;;    nothing, one nested and one not. Our conclusion is, no, it makes not
+;;    difference, so there is little pointing in putting a grouping construct 
in,
+;;    unless we do something intelligent.
+;;    
+
+;; #+BEGIN_SRC emacs-lisp
+(bench
+ (with-current-buffer
+     (current-buffer)
+   (with-current-buffer
+       (current-buffer))))
+;; #+END_SRC
+
+;; #+RESULTS:
+;; : 1.001554e-01
+
+
+;; #+BEGIN_SRC emacs-lisp
+(bench
+ (with-current-buffer
+     (current-buffer))
+ (with-current-buffer
+     (current-buffer)))
+;; #+END_SRC
+
+;; #+RESULTS:
+;; : 1.205835e-01
+
+;; *** How fast is point
+
+;;    m-buffer-at provides stateless functions, but how much overhead does this
+;;    introduce. We try this with the simplest function I can think of, which 
is
+;;    point. The various forms look different here -- because we have a
+;;    `current-buffer' call in, but not with `point'. But then, effectively,
+;;    `point' must call `current-buffer' somewhere as part of its 
implementation,
+;;    so this difference is fair.
+
+;;    We conclude that m-buffer is about 100x slower for calling `point', even
+;;    when the buffer does not actually need to be changed. So, a lot slower.
+
+;; #+BEGIN_SRC emacs-lisp
+(bench
+ (point))
+;; #+END_SRC
+
+;; #+RESULTS:
+;; : -1.722546e-03
+
+;; #+BEGIN_SRC emacs-lisp
+(bench
+ (with-current-buffer
+     (current-buffer)
+   (point)))
+;; #+END_SRC
+
+;; #+RESULTS:
+;; : 3.669245e-02
+
+;; #+BEGIN_SRC emacs-lisp
+(bench
+ (m-buffer-at-point
+  (current-buffer)))
+;; #+END_SRC
+
+;; #+RESULTS:
+;; : 1.011448e-01
diff --git a/m-buffer-doc.org b/m-buffer-doc.org
index c869136dd4..4cf5d1ae37 100644
--- a/m-buffer-doc.org
+++ b/m-buffer-doc.org
@@ -56,6 +56,13 @@ m-buffer-macro.el provides some general purpose macros for:
 #+include: "m-buffer-macro.org" :minlevel 2
 
 
+* m-buffer-benchmark
+
+m-buffer-benchmark.el provides no functions, but is a set of benchmarks to
+give some idea of how much overhead various m-buffer functions entail.
+
+#+include: "m-buffer-benchmark.org" :minlevel 2
+
 * Roadmap
 
 ** 0.11
diff --git a/m-buffer-macro.el b/m-buffer-macro.el
index 44119a6674..d716ee5bb8 100644
--- a/m-buffer-macro.el
+++ b/m-buffer-macro.el
@@ -28,7 +28,11 @@
 ;; the macro starts.
 
 ;; These macros are quite useful, but with the exception of
-;; `m-buffer-with-markers', they are mostly meant to underpin `m-buffer-at'.
+;; `m-buffer-with-markers', they are mostly meant to underpin `m-buffer-at'. 
The
+;; aim is that all the cases where one of these macros is used with a single 
form
+;; from core Emacs should be provided by m-buffer-at (although this is not the
+;; case yet). These macros might be more efficient if there are a lot of calls 
to
+;; group together.
 
 ;;; Code:
 
@@ -39,7 +43,6 @@
 ;; `m-buffer-nil-marker', but it can be a bit painful. This form looks like a
 ;; `let' form, but removes markers at the end.
 
-
 ;; #+begin_src emacs-lisp
 (defmacro m-buffer-with-markers (varlist &rest body)
   "Bind variables after VARLIST then eval BODY.
@@ -115,8 +118,6 @@ If a two element, it is a buffer and position."
                ,@body)
            (error "m-buffer-with-current-location requires a list of one or 
two elements"))))))
 
-
 (provide 'm-buffer-macro)
 ;;; m-buffer-macro.el ends here
 ;; #+end_src
-