Example of threads and concurrency?

[Eric Abrahamsen]

I've read the chapter on threads in the manual, and sort of understand
it theoretically, but not really in practice.

Can someone look at the below and tell me if it makes sense? I'm trying
to make a simple system where there's a global variable, and I update
the variable with a time-consuming/network-bound computation. I want the
computation to happen in a thread so it doesn't block, and I want no
other code to touch the variable while the computation is happening.

The following works when I run it, but I have no idea if this is
actually how you do it.

#+begin_src emacs-lisp
(defvar important-data-variable nil
  "Important variable holding important data.

Our goal is to update this data.")

(defvar important-data-mutex (make-mutex))

(defun update-important-data ()
  (with-mutex important-data-mutex
   (let ((result '(1 2 3))) ; Slow function here.
     (setq important-data-variable result))))

(defun update-data-in-thread ()
  (let* ((thread (make-thread #'update-important-data))
         (timer (run-at-time
                 10 nil
                 `(lambda ()
                    (when (thread-alive-p ,thread)
                      (thread-signal ,thread 'give-it-up))))))
    (thread-join thread)))
#+end_src

Is everything in the right place? It just occurs to me that If I put
`thread-join' at the bottom of `update-data-in-thread' then it will
effectively be synchronous after all! So I put that somewhere else, or I
don't call it at all.

Other questions:

1. Other code just has to know that it can't touch
   `important-data-variable' without holding `important-data-mutex',
   right?
2. I want the timer to signal the thread to give up after ten seconds --
   do I need to put anything in `update-important-data' that handles
   that signal?
3. What do condition vars actually do? The manual has an example that
   looks just like what I'm doing above:

   (with-mutex mutex
     (setq global-variable (some-computation))
     (condition-notify cond-var))

   What is cond-var doing here?

It seems like both mutexes and cond-vars are there so other code knows
when to keep its hands off `important-data-variable', but I don't 
understand how they're actually used.

Any light shed would be very welcome!

Eric