30
Emacs Deferred Documentation Release 0.3.2 SAKURAI Masashi February 06, 2016

Emacs Deferred Documentation€¦ · 2 deferred.el manual 5 ... •The anaphoric variable :el:var:‘it‘ holds a deferred object in the previous line. •The next deferred task

  • Upload
    others

  • View
    12

  • Download
    0

Embed Size (px)

Citation preview

Page 1: Emacs Deferred Documentation€¦ · 2 deferred.el manual 5 ... •The anaphoric variable :el:var:‘it‘ holds a deferred object in the previous line. •The next deferred task

Emacs Deferred DocumentationRelease 0.3.2

SAKURAI Masashi

February 06, 2016

Page 2: Emacs Deferred Documentation€¦ · 2 deferred.el manual 5 ... •The anaphoric variable :el:var:‘it‘ holds a deferred object in the previous line. •The next deferred task
Page 3: Emacs Deferred Documentation€¦ · 2 deferred.el manual 5 ... •The anaphoric variable :el:var:‘it‘ holds a deferred object in the previous line. •The next deferred task

Contents

1 Installation 31.1 Installing from Melpa . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Installing from Marmalade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.3 Installing from Git . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2 deferred.el manual 52.1 Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2.1.1 Basic usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.1.2 Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.1.3 Commands and Sub-process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.1.4 HTTP GET : Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.1.5 HTTP Get : Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.1.6 Parallel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.1.7 Deferred Combination : try-catch-finally . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.1.8 Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.1.9 Loop and Animation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92.1.10 Wrapping asynchronous function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

3 concurrent.el manual 11

4 deferred.el API 134.1 Basic functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134.2 Utility functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144.3 Wrapper functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144.4 Primitive functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154.5 Utility Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

5 concurrent.el API 175.1 Pseudo-thread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175.2 Generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175.3 Semaphore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175.4 Signal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185.5 Dataflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

6 Resources for deferred.el/concurrent.el development 216.1 How to build document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

7 Indices and tables 23

i

Page 4: Emacs Deferred Documentation€¦ · 2 deferred.el manual 5 ... •The anaphoric variable :el:var:‘it‘ holds a deferred object in the previous line. •The next deferred task

ii

Page 5: Emacs Deferred Documentation€¦ · 2 deferred.el manual 5 ... •The anaphoric variable :el:var:‘it‘ holds a deferred object in the previous line. •The next deferred task

Emacs Deferred Documentation, Release 0.3.2

Contents:

Contents 1

Page 6: Emacs Deferred Documentation€¦ · 2 deferred.el manual 5 ... •The anaphoric variable :el:var:‘it‘ holds a deferred object in the previous line. •The next deferred task

Emacs Deferred Documentation, Release 0.3.2

2 Contents

Page 7: Emacs Deferred Documentation€¦ · 2 deferred.el manual 5 ... •The anaphoric variable :el:var:‘it‘ holds a deferred object in the previous line. •The next deferred task

CHAPTER 1

Installation

1.1 Installing from Melpa

If you have already used Melpa to install some other package then all you have to do is:

M-x package-install RET deferred RET

1.2 Installing from Marmalade

WRITE HERE

1.3 Installing from Git

If you want to contribute to deferred and concurrent you should run it directly from the Git reposiotry.

First get the repository:

$ git clone git://github.com/kiwanami/emacs-deferred.git

Then add this to your init.el:

(add-to-list 'load-path "/path/to/emacs-deferred")(require 'deferred)(require 'concurrent)

To build deferred and concurrent manually:

WRITE HERE

3

Page 8: Emacs Deferred Documentation€¦ · 2 deferred.el manual 5 ... •The anaphoric variable :el:var:‘it‘ holds a deferred object in the previous line. •The next deferred task

Emacs Deferred Documentation, Release 0.3.2

4 Chapter 1. Installation

Page 9: Emacs Deferred Documentation€¦ · 2 deferred.el manual 5 ... •The anaphoric variable :el:var:‘it‘ holds a deferred object in the previous line. •The next deferred task

CHAPTER 2

deferred.el manual

2.1 Sample

You can find following sample codes in deferred-sample.el. Executing eval-last-sexp (C-x C-e), youcan try those codes.

2.1.1 Basic usage

This is a basic deferred chain. This code puts some outputs into message buffer, and then require a number fromminibuffer.

Chain:

(deferred:$(deferred:next(lambda () (message "deferred start")))

(deferred:nextc it(lambda ()

(message "chain 1")1))

(deferred:nextc it(lambda (x)(message "chain 2 : %s" x)))

(deferred:nextc it(lambda ()(read-minibuffer "Input a number: ")))

(deferred:nextc it(lambda (x)(message "Got the number : %i" x)))

(deferred:error it(lambda (err)(message "Wrong input : %s" err))))

• This s-exp returns immediately.

• Asynchronous tasks start subsequently.

• The macro deferred:$ chains deferred objects.

• The anaphoric variable :el:var:‘it‘ holds a deferred object in the previous line.

• The next deferred task receives the value that is returned by the previous deferred one.

5

Page 10: Emacs Deferred Documentation€¦ · 2 deferred.el manual 5 ... •The anaphoric variable :el:var:‘it‘ holds a deferred object in the previous line. •The next deferred task

Emacs Deferred Documentation, Release 0.3.2

• Inputting a wrong value, such as alphabets, this s-exp raises an error. The error is caught by the errorbackfunction defined by deferred:error.

2.1.2 Timer

After evaluating this s-exp and waiting for 1 second, a message is shown in the minibuffer.

Timer:

(deferred:$(deferred:wait 1000) ; 1000msec(deferred:nextc it(lambda (x)

(message "Timer sample! : %s msec" x))))

• The next deferred task subsequent to deferred:wait receives the actual elapse time in millisecond.

2.1.3 Commands and Sub-process

This s-exp inserts the result that is performed by the command ‘ls -la’. (This s-exp may not run in windows. Try ‘dir’command.)

Command process:

(deferred:$(deferred:process "ls" "-la")(deferred:nextc it(lambda (x) (insert x))))

• This s-exp hardly blocks Emacs because of asynchronous mechanisms.

2.1.4 HTTP GET : Text

This s-exp inserts a text from http://www.gnu.org asynchronously. (You can clear the result with undo command.)

HTTP GET:

(require 'url)

(deferred:$(deferred:url-retrieve "http://www.gnu.org")(deferred:nextc it(lambda (buf)(insert (with-current-buffer buf (buffer-string)))(kill-buffer buf))))

2.1.5 HTTP Get : Image

This s-exp inserts an image from google asynchronously.

Get an image:

(deferred:$(deferred:url-retrieve "http://www.google.co.jp/intl/en_com/images/srpr/logo1w.png")(deferred:nextc it

6 Chapter 2. deferred.el manual

Page 11: Emacs Deferred Documentation€¦ · 2 deferred.el manual 5 ... •The anaphoric variable :el:var:‘it‘ holds a deferred object in the previous line. •The next deferred task

Emacs Deferred Documentation, Release 0.3.2

(lambda (buf)(insert-image(create-image(let ((data (with-current-buffer buf (buffer-string))))(substring data (+ (string-match "\n\n" data) 2)))

'png t))(kill-buffer buf))))

2.1.6 Parallel

This s-exp retrieves two images from google concurrently and wait for the both results. Then, the file sizes of theimages are inserted the current buffer.

Parallel deferred:

(deferred:$(deferred:parallel(lambda ()(deferred:url-retrieve "http://www.google.co.jp/intl/en_com/images/srpr/logo1w.png"))

(lambda ()(deferred:url-retrieve "http://www.google.co.jp/images/srpr/nav_logo14.png")))

(deferred:nextc it(lambda (buffers)(loop for i in buffers

do(insert(format"size: %s\n"(with-current-buffer i (length (buffer-string)))))

(kill-buffer i)))))

• The function ‘deferred:parallel’ runs asynchronous tasks concurrently.

• The function wait for all results, regardless normal or abnormal. Then, the subsequent tasks are executed.

• The next task receives a list of the results.

– The order of the results is corresponding to one of the argument.

– Giving an alist of tasks as the argument, the results alist is returned.

2.1.7 Deferred Combination : try-catch-finally

This s-exp executes following tasks:

• Getting an image by wget command,

• Resizing the image by convert command in ImageMagick,

• Insert the re-sized image into the current buffer. You can construct the control structure of deferred tasks, liketry-catch-finally in Java.

Get an image by wget and resize by ImageMagick:

(deferred:$

;; try(deferred:$(deferred:process "wget" "-O" "a.jpg" "http://www.gnu.org/software/emacs/tour/images/splash.png")

2.1. Sample 7

Page 12: Emacs Deferred Documentation€¦ · 2 deferred.el manual 5 ... •The anaphoric variable :el:var:‘it‘ holds a deferred object in the previous line. •The next deferred task

Emacs Deferred Documentation, Release 0.3.2

(deferred:nextc it(lambda () (deferred:process "convert" "a.jpg" "-resize" "100x100" "jpg:b.jpg")))

(deferred:nextc it(lambda ()

(clear-image-cache)(insert-image (create-image (expand-file-name "b.jpg") 'jpeg nil)))))

;; catch(deferred:error it ;(lambda (err)

(insert "Can not get a image! : " err)))

;; finally(deferred:nextc it(lambda ()(deferred:parallel

(lambda () (delete-file "a.jpg"))(lambda () (delete-file "b.jpg")))))

(deferred:nextc it(lambda (x) (message ">> %s" x))))

• In this case, the deferred tasks are statically connected.

Here is an another sample code for try-catch-finally blocks. This is simpler than above code because of the ‘de-ferred:try’ macro. (Note: They bring the same results practically, but are not perfectly identical. The ‘finally’ task maynot be called because of asynchrony.)

Try-catch-finally:

(deferred:$(deferred:try(deferred:$

(deferred:process "wget" "-O" "a.jpg" "http://www.gnu.org/software/emacs/tour/images/splash.png")(deferred:nextc it

(lambda () (deferred:process "convert" "a.jpg" "-resize" "100x100" "jpg:b.jpg")))(deferred:nextc it

(lambda ()(clear-image-cache)(insert-image (create-image (expand-file-name "b.jpg") 'jpeg nil)))))

:catch(lambda (err) (insert "Can not get a image! : " err)):finally(lambda ()

(delete-file "a.jpg")(delete-file "b.jpg")))

(deferred:nextc it(lambda (x) (message ">> %s" x))))

2.1.8 Timeout

Although a long time command is executed (3 second sleeping), the task is canceled by timeout for 1 second.

The function ‘deferred:earlier’ also runs asynchronous tasks concurrently, however, the next deferred task receives thefirst result. The other results and tasks will be canceled.

Timeout Process:

8 Chapter 2. deferred.el manual

Page 13: Emacs Deferred Documentation€¦ · 2 deferred.el manual 5 ... •The anaphoric variable :el:var:‘it‘ holds a deferred object in the previous line. •The next deferred task

Emacs Deferred Documentation, Release 0.3.2

(deferred:$(deferred:earlier(deferred:process "sh" "-c" "sleep 3 | echo 'hello!'")(deferred:$

(deferred:wait 1000) ; timeout msec(deferred:nextc it (lambda () "canceled!"))))

(deferred:nextc it(lambda (x) (insert x))))

• Changing longer timeout for ‘deferred:wait’, the next task receives a result of the command.

• When a task finishes abnormally, the task is ignored.

– When all tasks finishes abnormally, the next task receives nil.

• The functions ‘deferred:parallel’ and ‘deferred:earlier’ may be corresponding to ‘and’ and ‘or’, respectively.

Here is an another sample code for timeout, employing ‘deferred:timeout’ macro.

Timeout macro:

(deferred:$(deferred:timeout1000 "canceled!"(deferred:process "sh" "-c" "sleep 3 | echo 'hello!'"))

(deferred:nextc it(lambda (x) (insert x))))

2.1.9 Loop and Animation

This s-exp plays an animation at the cursor position for few seconds. Then, you can move cursor freely, because theanimation does not block Emacs.

Returning a deferred object in the deferred tasks, the returned task is executed before the next deferred one that isstatically connected on the source code. (In this case, the interrupt task is dynamically connected.)

Employing a recursive structure of deferred tasks, you can construct a deferred loop. It may seem the multi-thread inEmacs Lisp.

Loop and animation:

(lexical-let ((count 0) (anm "-/|\\-")(end 50) (pos (point))(wait-time 50))

(deferred:$(deferred:next

(lambda (x) (message "Animation started.")))

(deferred:nextc it(deferred:lambda (x)

(save-excursion(when (< 0 count)(goto-char pos) (delete-char 1))

(insert (char-to-string(aref anm (% count (length anm))))))

(if (> end (incf count)) ; return nil to stop this loop(deferred:nextc (deferred:wait wait-time) self)))) ; return the deferred

(deferred:nextc it(lambda (x)

2.1. Sample 9

Page 14: Emacs Deferred Documentation€¦ · 2 deferred.el manual 5 ... •The anaphoric variable :el:var:‘it‘ holds a deferred object in the previous line. •The next deferred task

Emacs Deferred Documentation, Release 0.3.2

(save-excursion(goto-char pos) (delete-char 1))

(message "Animation finished.")))))

• ‘deferred:lambda’ is an anaphoric macro in which ‘self’ refers itself. It is convenient to construct a recursivestructure.

2.1.10 Wrapping asynchronous function

Let’s say you have an asynchronous function which takes a callback. For example, dbus.el, xml-rpc.el and web-socket.el has such kind of asynchronous APIs. To use such libraries with deferred.el, you can make an unregis-tered deferred object using deferred:new and then start the deferred callback queue using deferred:callback-post inthe callback given to the asynchronous function. If the asynchronous function supports “errorback”, you can usedeferred:errorback-post to pass the error information to the following callback queue.

In the following example, run-at-time is used as an example for the asynchronous function. Deferred.el already hasdeferred:wait for this purpose so that you don’t need the following code if you want to use run-at-time.

(deferred:$(deferred:next(lambda ()(message "1")1))

(deferred:nextc it(lambda (x)(lexical-let ((d (deferred:new #'identity)))

(run-at-time 0 nil (lambda (x);; Start the following callback queue now.(deferred:callback-post d x))

x);; Return the unregistered (not yet started) callback;; queue, so that the following queue will wait until it;; is started.d)))

;; You can connect deferred callback queues(deferred:nextc it(lambda (x)(message "%s" (1+ x)))))

10 Chapter 2. deferred.el manual

Page 15: Emacs Deferred Documentation€¦ · 2 deferred.el manual 5 ... •The anaphoric variable :el:var:‘it‘ holds a deferred object in the previous line. •The next deferred task

CHAPTER 3

concurrent.el manual

WRITE HERE

11

Page 16: Emacs Deferred Documentation€¦ · 2 deferred.el manual 5 ... •The anaphoric variable :el:var:‘it‘ holds a deferred object in the previous line. •The next deferred task

Emacs Deferred Documentation, Release 0.3.2

12 Chapter 3. concurrent.el manual

Page 17: Emacs Deferred Documentation€¦ · 2 deferred.el manual 5 ... •The anaphoric variable :el:var:‘it‘ holds a deferred object in the previous line. •The next deferred task

CHAPTER 4

deferred.el API

4.1 Basic functions

Function deferred:next( &optional callback, arg)Create a deferred object and schedule executing.

:Arguments:CALLBACK

a function with zero or one argument:Return: a deferred object

This function is a short cut of following code::

(deferred:callback-post (deferred:new callback)).

Function deferred:nextc(d, callback)Create a deferred object with OK callback and connect it tothe given deferred object.

:Arguments:D

a deferred objectCALLBACK

a function with zero or one argument:Return: a deferred object

Return a deferred object that wrap the given callbackfunction. Then, connect the created deferred object with thegiven deferred object.

Function deferred:error(d, callback)Create a deferred object with ERRORBACK and connect it to thegiven deferred object D.

:Arguments:D

a deferred objectERRORBACK

a function with zero or one argument:Return: a deferred object

13

Page 18: Emacs Deferred Documentation€¦ · 2 deferred.el manual 5 ... •The anaphoric variable :el:var:‘it‘ holds a deferred object in the previous line. •The next deferred task

Emacs Deferred Documentation, Release 0.3.2

Return a deferred object that wraps the given function as anERRORBACK. Then, connect the created deferred object with thegiven deferred object. The given ERRORBACK function catches theerror occurred in the previous task.

If this function does not throw an error, the subsequent callbackfunctions are executed.

Function deferred:cancel(d)Cancel all callbacks and deferred chain in the deferred object.

Function deferred:watch(d, callback)Create a deferred object with watch task and connect it to the given deferred object.The watch task CALLBACK can not affect deferred chains withreturn values. This function is used in following purposes,simulation of try-finally block in asynchronous tasks, progressmonitoring of tasks.

Function deferred:wait(msec)Return a deferred object scheduled at MSEC millisecond later.

Function deferred:$( &rest elements)Anaphoric function chain macro for deferred chains.

4.2 Utility functions

Function deferred:loop(times-or-list, func)Return a iteration deferred object.

Function deferred:parallel( &rest args)Return a deferred object that calls given deferred objects orfunctions in parallel and wait for all callbacks. The followingdeferred task will be called with an array of the returnvalues. ARGS can be a list or an alist of deferred objects orfunctions.

Function deferred:earlier( &rest args)Return a deferred object that calls given deferred objects orfunctions in parallel and wait for the first callback. Thefollowing deferred task will be called with the first returnvalue. ARGS can be a list or an alist of deferred objects orfunctions.

4.3 Wrapper functions

Function deferred:call(f &rest , args)Call the given function asynchronously.

Function deferred:apply(f &optional , args)Call the given function asynchronously.

Function deferred:process(command &rest , args)

14 Chapter 4. deferred.el API

Page 19: Emacs Deferred Documentation€¦ · 2 deferred.el manual 5 ... •The anaphoric variable :el:var:‘it‘ holds a deferred object in the previous line. •The next deferred task

Emacs Deferred Documentation, Release 0.3.2

A deferred wrapper of `start-process'. Return a deferredobject. The process name and buffer name of the argument of the`start-process' are generated by this function automatically.The next deferred object receives stdout string from the commandprocess.

Function deferred:process-shell(command &rest , args)A deferred wrapper of `start-process-shell-command'. Return a deferredobject. The process name and buffer name of the argument of the`start-process-shell-command' are generated by this function automatically.The next deferred object receives stdout string from the commandprocess.

Function deferred:process-buffer(command &rest , args)A deferred wrapper of `start-process'. Return a deferredobject. The process name and buffer name of the argument of the`start-process' are generated by this function automatically.The next deferred object receives stdout buffer from the commandprocess.

Function deferred:process-shell-buffer(command &rest , args)A deferred wrapper of `start-process-shell-command'. Return a deferredobject. The process name and buffer name of the argument of the`start-process-shell-command' are generated by this function automatically.The next deferred object receives stdout buffer from the commandprocess.

Function deferred:wait-idle(msec)Return a deferred object which will run when Emacs has beenidle for MSEC millisecond.

Function deferred:url-retrieve()

Function deferred:url-get()

Function deferred:url-post()

4.4 Primitive functions

Function deferred:new( &optional callback)Create a deferred object.

Function deferred:succeed( &optional arg)Create a synchronous deferred object.

Function deferred:fail( &optional arg)Create a synchronous deferred object.

Function deferred:callback(d &optional , arg)Start deferred chain with a callback message.

Function deferred:callback-post(d &optional , arg)Add the deferred object to the execution queue.

Function deferred:errorback(d &optional , arg)Start deferred chain with an errorback message.

Function deferred:errorback-post(d &optional , arg)Add the deferred object to the execution queue.

4.4. Primitive functions 15

Page 20: Emacs Deferred Documentation€¦ · 2 deferred.el manual 5 ... •The anaphoric variable :el:var:‘it‘ holds a deferred object in the previous line. •The next deferred task

Emacs Deferred Documentation, Release 0.3.2

4.5 Utility Macros

Function deferred:try(d &key , catch, finally)Try-catch-finally macro. This macro simulates thetry-catch-finally block asynchronously. CATCH and FINALLY can benil. Because of asynchrony, this macro does not ensure that thetask FINALLY should be called.

Function deferred:timeout(timeout-msec, timeout-form, d)Time out macro on a deferred task D. If the deferred task Ddoes not complete within TIMEOUT-MSEC, this macro cancels thedeferred task and return the TIMEOUT-FORM.

Function deferred:processc(d, command &rest , args)Process chain of ˙0api:el.function.deferred:processdeferred0-api:el.function.deferred:process`deferred:process'.

Function deferred:process-bufferc(d, command &rest , args)Process chain of ˙0api:el.function.deferred:process0bufferdeferred0-api:el.function.deferred:process0buffer`deferred:process-buffer'.

Function deferred:process-shellc(d, command &rest , args)Process chain of ˙0api:el.function.deferred:processdeferred0-api:el.function.deferred:process`deferred:process'.

Function deferred:process-shell-bufferc(d, command &rest , args)Process chain of ˙0api:el.function.deferred:process0bufferdeferred0-api:el.function.deferred:process0buffer`deferred:process-buffer'.

16 Chapter 4. deferred.el API

Page 21: Emacs Deferred Documentation€¦ · 2 deferred.el manual 5 ... •The anaphoric variable :el:var:‘it‘ holds a deferred object in the previous line. •The next deferred task

CHAPTER 5

concurrent.el API

5.1 Pseudo-thread

Function cc:thread(wait-time-msec &rest , body)Return a thread object.

5.2 Generator

Function cc:generator(callback &rest , body)Create a generator object. If BODY has `yield' symbols, itmeans calling callback function CALLBACK.

5.3 Semaphore

Function cc:semaphore-create(permits-num)Return a semaphore object with PERMITS-NUM permissions.

Function cc:semaphore-acquire(semaphore)Acquire an execution permission and return deferred object to chain.If this semaphore object has permissions, the subsequent deferredtask is executed immediately. If this semaphore object has nopermissions, the subsequent deferred task is blocked. After thepermission is returned, the task is executed.

Function cc:semaphore-release(semaphore)Release an execution permission. The programmer is responsible to return the permissions.

Function cc:semaphore-with(semaphore, body-func &optional , error-func)Execute the task BODY-FUNC asynchronously with the semaphore block.

Function cc:semaphore-release-all(semaphore)Release all permissions for resetting the semaphore object.If the semaphore object has some blocked tasks, this functionreturn a list of the tasks and clear the list of the blockedtasks in the semaphore object.

Function cc:semaphore-interrupt-all(semaphore)Clear the list of the blocked tasks in the semaphore and return a deferred object to chain.This function is used for the interruption cases.

17

Page 22: Emacs Deferred Documentation€¦ · 2 deferred.el manual 5 ... •The anaphoric variable :el:var:‘it‘ holds a deferred object in the previous line. •The next deferred task

Emacs Deferred Documentation, Release 0.3.2

5.4 Signal

Function cc:signal-channel( &optional name, parent-channel)Create a channel.NAME is a channel name for debug.PARENT-CHANNEL is an upstream channel. The observers of this channel can receive the upstream signals.In the case of using the function ˙0api:el.function.cc:signal0-sendconcurrent0api:el.function.cc:signal0send`cc:signal-send', the observers of the upstream channel can not receive the signals of this channel. The function ˙0-api:el.function.cc:signal0send0globalconcurrent0api:el.function.cc:signal0-send0global`cc:signal-send-global' can send a signal to the upstream channels from the downstream channels.

Function cc:signal-connect(channel, event-sym &optional , callback)Append an observer for EVENT-SYM of CHANNEL and return a deferred object.If EVENT-SYM is `t', the observer receives all signals of the channel.If CALLBACK function is given, the deferred object executes theCALLBACK function asynchronously. One can connect subsequenttasks to the returned deferred object.

Function cc:signal-send(channel, event-sym &rest , args)Send a signal to CHANNEL. If ARGS values are given, observers can get the values by following code: (lambda (event) (destructuring-bind (event-sym (args)) event ... )).

Function cc:signal-send-global(channel, event-sym &rest , args)Send a signal to the most upstream channel.

Function cc:signal-disconnect(channel, deferred)Remove the observer object DEFERRED from CHANNEL and returnthe removed deferred object.

Function cc:signal-disconnect-all(channel)Remove all observers.

5.5 Dataflow

Function cc:dataflow-environment( &optional parent-env, test-func, channel)Create a dataflow environment.PARENT-ENV is the default environment. If this environment doesn't have the entry A and the parent one has the entry A, this environment can return the entry A. One can override the entry, setting another entry A to this environment.TEST-FUNC is a test function that compares the entry keys. The default function is `equal'.CHANNEL is a channel object that sends signals of variable events. Observers can receive following signals:

``get-first``the fist referrer is waiting for binding

``get-waiting``another referrer is waiting for binding

``set``a value is bound

``get``returned a bound value

``clear``cleared one entry

``clear-all``cleared all entries

Function cc:dataflow-get(df, key)

18 Chapter 5. concurrent.el API

Page 23: Emacs Deferred Documentation€¦ · 2 deferred.el manual 5 ... •The anaphoric variable :el:var:‘it‘ holds a deferred object in the previous line. •The next deferred task

Emacs Deferred Documentation, Release 0.3.2

Return a deferred object that can refer the value which is indicated by KEY.If DF has the entry that bound value, the subsequent deferred task is executed immediately.If not, the task is deferred till a value is bound.

Function cc:dataflow-get-sync(df, key)Return the value which is indicated by KEY synchronously.If the environment DF doesn't have an entry of KEY, this function returns nil.

Function cc:dataflow-set(df, key, value)Bind the VALUE to KEY in the environment DF.If DF already has the bound entry of KEY, this function throws an error signal.VALUE can be nil as a value.

Function cc:dataflow-clear(df, key)Clear the entry which is indicated by KEY.This function does nothing for the waiting deferred objects.

Function cc:dataflow-get-avalable-pairs(df)Return an available key-value alist in the environment DF and the parent ones.

Function cc:dataflow-get-waiting-keys(df)Return a list of keys which have waiting deferred objects in the environment DF and the parent ones.

Function cc:dataflow-clear-all(df)Clear all entries in the environment DF.This function does nothing for the waiting deferred objects.

Function cc:dataflow-connect(df, event-sym &optional , callback)Append an observer for EVENT-SYM of the channel of DF and return a deferred object.See the docstring of ˙0api:el.function.cc:dataflow0environmentconcurrent0-api:el.function.cc:dataflow0environment`cc:dataflow-environment' for details.

5.5. Dataflow 19

Page 24: Emacs Deferred Documentation€¦ · 2 deferred.el manual 5 ... •The anaphoric variable :el:var:‘it‘ holds a deferred object in the previous line. •The next deferred task

Emacs Deferred Documentation, Release 0.3.2

20 Chapter 5. concurrent.el API

Page 25: Emacs Deferred Documentation€¦ · 2 deferred.el manual 5 ... •The anaphoric variable :el:var:‘it‘ holds a deferred object in the previous line. •The next deferred task

CHAPTER 6

Resources for deferred.el/concurrent.el development

6.1 How to build document

Document of deferred.el and concurrent.el are build using Sphinx and sphinxcontrib-emacs. It is available via read thedocs.

To build document, you need to install Sphinx and sphinxcontrib-emacs, for example, using pip install:

cd PATH/TO/emacs-deferredpip install Sphinxpip install -r doc/requirements.txt

Then, goto doc/ directory and build document:

cd doc/make html

You have html document in doc/build/html/.

If autodocument does not fetch updated docstrings from *.el files, use make clean html instead.

21

Page 26: Emacs Deferred Documentation€¦ · 2 deferred.el manual 5 ... •The anaphoric variable :el:var:‘it‘ holds a deferred object in the previous line. •The next deferred task

Emacs Deferred Documentation, Release 0.3.2

22 Chapter 6. Resources for deferred.el/concurrent.el development

Page 27: Emacs Deferred Documentation€¦ · 2 deferred.el manual 5 ... •The anaphoric variable :el:var:‘it‘ holds a deferred object in the previous line. •The next deferred task

CHAPTER 7

Indices and tables

• genindex

• modindex

• search

23

Page 28: Emacs Deferred Documentation€¦ · 2 deferred.el manual 5 ... •The anaphoric variable :el:var:‘it‘ holds a deferred object in the previous line. •The next deferred task

Emacs Deferred Documentation, Release 0.3.2

24 Chapter 7. Indices and tables

Page 29: Emacs Deferred Documentation€¦ · 2 deferred.el manual 5 ... •The anaphoric variable :el:var:‘it‘ holds a deferred object in the previous line. •The next deferred task

Index

Ccc:dataflow-clear

Emacs Lisp function, 19cc:dataflow-clear-all

Emacs Lisp function, 19cc:dataflow-connect

Emacs Lisp function, 19cc:dataflow-environment

Emacs Lisp function, 18cc:dataflow-get

Emacs Lisp function, 18cc:dataflow-get-avalable-pairs

Emacs Lisp function, 19cc:dataflow-get-sync

Emacs Lisp function, 19cc:dataflow-get-waiting-keys

Emacs Lisp function, 19cc:dataflow-set

Emacs Lisp function, 19cc:generator

Emacs Lisp function, 17cc:semaphore-acquire

Emacs Lisp function, 17cc:semaphore-create

Emacs Lisp function, 17cc:semaphore-interrupt-all

Emacs Lisp function, 17cc:semaphore-release

Emacs Lisp function, 17cc:semaphore-release-all

Emacs Lisp function, 17cc:semaphore-with

Emacs Lisp function, 17cc:signal-channel

Emacs Lisp function, 18cc:signal-connect

Emacs Lisp function, 18cc:signal-disconnect

Emacs Lisp function, 18cc:signal-disconnect-all

Emacs Lisp function, 18cc:signal-send

Emacs Lisp function, 18cc:signal-send-global

Emacs Lisp function, 18cc:thread

Emacs Lisp function, 17

Ddeferred:$

Emacs Lisp function, 14deferred:apply

Emacs Lisp function, 14deferred:call

Emacs Lisp function, 14deferred:callback

Emacs Lisp function, 15deferred:callback-post

Emacs Lisp function, 15deferred:cancel

Emacs Lisp function, 14deferred:earlier

Emacs Lisp function, 14deferred:error

Emacs Lisp function, 13deferred:errorback

Emacs Lisp function, 15deferred:errorback-post

Emacs Lisp function, 15deferred:fail

Emacs Lisp function, 15deferred:loop

Emacs Lisp function, 14deferred:new

Emacs Lisp function, 15deferred:next

Emacs Lisp function, 13deferred:nextc

Emacs Lisp function, 13deferred:parallel

Emacs Lisp function, 14

25

Page 30: Emacs Deferred Documentation€¦ · 2 deferred.el manual 5 ... •The anaphoric variable :el:var:‘it‘ holds a deferred object in the previous line. •The next deferred task

Emacs Deferred Documentation, Release 0.3.2

deferred:processEmacs Lisp function, 14

deferred:process-bufferEmacs Lisp function, 15

deferred:process-buffercEmacs Lisp function, 16

deferred:process-shellEmacs Lisp function, 15

deferred:process-shell-bufferEmacs Lisp function, 15

deferred:process-shell-buffercEmacs Lisp function, 16

deferred:process-shellcEmacs Lisp function, 16

deferred:processcEmacs Lisp function, 16

deferred:succeedEmacs Lisp function, 15

deferred:timeoutEmacs Lisp function, 16

deferred:tryEmacs Lisp function, 16

deferred:url-getEmacs Lisp function, 15

deferred:url-postEmacs Lisp function, 15

deferred:url-retrieveEmacs Lisp function, 15

deferred:waitEmacs Lisp function, 14

deferred:wait-idleEmacs Lisp function, 15

deferred:watchEmacs Lisp function, 14

EEmacs Lisp function

cc:dataflow-clear, 19cc:dataflow-clear-all, 19cc:dataflow-connect, 19cc:dataflow-environment, 18cc:dataflow-get, 18cc:dataflow-get-avalable-pairs, 19cc:dataflow-get-sync, 19cc:dataflow-get-waiting-keys, 19cc:dataflow-set, 19cc:generator, 17cc:semaphore-acquire, 17cc:semaphore-create, 17cc:semaphore-interrupt-all, 17cc:semaphore-release, 17cc:semaphore-release-all, 17cc:semaphore-with, 17cc:signal-channel, 18

cc:signal-connect, 18cc:signal-disconnect, 18cc:signal-disconnect-all, 18cc:signal-send, 18cc:signal-send-global, 18cc:thread, 17deferred:$, 14deferred:apply, 14deferred:call, 14deferred:callback, 15deferred:callback-post, 15deferred:cancel, 14deferred:earlier, 14deferred:error, 13deferred:errorback, 15deferred:errorback-post, 15deferred:fail, 15deferred:loop, 14deferred:new, 15deferred:next, 13deferred:nextc, 13deferred:parallel, 14deferred:process, 14deferred:process-buffer, 15deferred:process-bufferc, 16deferred:process-shell, 15deferred:process-shell-buffer, 15deferred:process-shell-bufferc, 16deferred:process-shellc, 16deferred:processc, 16deferred:succeed, 15deferred:timeout, 16deferred:try, 16deferred:url-get, 15deferred:url-post, 15deferred:url-retrieve, 15deferred:wait, 14deferred:wait-idle, 15deferred:watch, 14

26 Index