Bruno Barbier <brubar...@gmail.com> writes: >> While reading the library header and `org-pending' docstring (btw, it >> should probably be a separate library, not a part of org-macs), > > I was feeling more and more like squatting the wrong file :-) > > Would "lisp/org-pending.el" be OK ? Or do you see a better place/name ?
org-pending sounds fine. Maybe org-pending-text to be more explicit. >> More or less, org-pending implements Elisp asynchronous process control, >> but the processes are associated with region, not the whole buffer. >> Hence, I feel that we should adopt terminology similar to the existing >> terminology for processes - process filters, process sentinels, sending >> signals to processes, etc. And similar API. > > The current `org-pending' doesn't know what a process is, or a thread. > The job of org-pending is only to let Emacs know that a given region > will be updated at some point later (much like what > `org-edit-src-code' does, when a source block is being edited > manually). > I've re-read the Elisp manual about asynchronous processes. The only > thing that seemed obvious to me, was to replace "feedbacks-handler" > with "sentinel". I also tried to simplify things and use REGION > instead of CONTENT where it make sense. Thanks. > Do you see something else ? Similar to process API, your library provides means to interact with process associated with the pending text - create them (40.4 Creating an Asynchronous Process), handle feedback (40.9.2 Process Filter Functions), handle on-done/fail/etc (40.10 Sentinels: Detecting Process Status Changes), kill/cancel execution (40.5 Deleting Processes, 40.8 Sending Signals to Processes), insert-log (strerr in Emacs processes) list pending (40.6 Process Information), org-pending-on-kill-buffer (40.11 Querying Before Exit), get information (`process-attributes', 40.12 Accessing Other Processes) I simply went across 40 Processes section of Elisp manual and I see parallels for pretty much every subsection; but the terminology _and API_ are different. >> Also, I am not sure if I like the idea of exposing raw PINFO alist and >> mutating it. In particular, I have doubts about mutating CONTENT. >> What we might do instead is implement PINFO as struct with custom >> accessors/setters. > > I went for this simple alist because it's more flexible (easy to add new > bindings) and less code than using a struct. And Org already uses lists > like this (params, info, etc.). Mutating CONTENT (or other essential > data) would be a very bad idea indeed; but it's like that for pretty > much everything with elisp. > > I'm OK to rewrite it using a cl-defstruct (to be honnest, I just > flipped a coin to decide between a struct or an alist :) ). I think that I need to elaborate. It is not necessarily a matter of alist vs. struct, but more about the API. I do not like the idea of mutating the alist entries directly. I'd rather expose an API to work with "pending" as an opaque object - send signals to it, get status, etc. struct is slightly better here because it automatically defines setters and getters for all the slots without a need to write extra boilerplate code. -- Ihor Radchenko // yantar92, Org mode contributor, Learn more about Org mode at <https://orgmode.org/>. Support Org development at <https://liberapay.com/org-mode>, or support my work at <https://liberapay.com/yantar92>