Re: Pending contents in org documents (Re: Asynchronous blocks for everything (was Re: ...))

[Ihor Radchenko <yantar92@posteo.net>]

Bruno Barbier <brubar.cs@gmail.com> writes:

> I rewrote the API, rename many things, moved the code around and
> sorted everything into heading/subheading sections.  This is hopefully
> less confusing and a lot simpler; and the documentation hopefully
> explains better how to use it.

Thanks! It does look more clear.

> The updated section "Commentary", in org-pending, describes the 3 steps
> that are needed to mark and use a pending region: a PENREG (I've renamed
> "PINFO" to "PENREG", for PENding REGion, more specific).

I feel that org-pending-penreg (org-pending-<pending region>) is
redundant. Maybe better use org-pending-region?

> WDYT of this version ?

Comments on org-pending-pendreg struct:

1. It is not clear why you need a separate ~virtual~ field. When
   ~region~ is nil it already implies that the pending region is
   virtual.

2. ~id~ field is semi-internal and assumed to be a number.
   Maybe we can do something more similar to Emacs process API:
   
   (make-process &rest ARGS)
   ...
   :name NAME -- NAME is name for process.  It is modified if necessary
   to make it unique.

   We can replace id with human-readable name that can also be supplied
   when creating a pending region

3. ~source~ field must match the ~region~ marker buffer. Then, why do we
   need this field at all? May as well just use (marker-buffer (car region))

On the design of ~org-pending~ and ~org-pending-task-connect~:

1. I feel confused about the overall design of the interaction between
   pending region and the associated task.

   Functions like ~org-pending-task-send-update~ imply that pending
   region is rather decoupled from from associated task and the task
   should arrange manually for sending updates to the pending region
   object.

   On the other hand, there is ~task-connection~ that is used to kill
   associated task/process or to "await" for it. This time, pending
   region is strongly coupled with the task, killing it upon deleting
   the pending region.

   I think that we need more (optional) coupling between pending region
   and the associated task. We should be able to get more information
   about the task from pending region side - get logs, current status,
   exit status, etc.

   More specifically, I think that we need (1) allow to pass task as an
   argument for ~org-pending~. (2) In ~org-pending-task-connect~, we
   should allow the task to be a process or timer object. Then, we can
   automatically arrange retrieving process/timer status from the task:
   
   Use process sentinel (maybe, modifying existing via ~add-function~)
   to arrange process status changes to be automatically submitted to
   the pending region;

   Get log updates via process filter

   Kill process via ~kill-process~

   Similar for timers.

   If the argument to ~org-pending-task-connect~ is a lambda, we can use
   the current approach you implemented on the branch.

2. ~org-pending-task-send-update~ name is confusing - it reads as if we
   send an update _to_ the task. Maybe better ~org-pending-region-update~?
   Then, we might even drop ~-sentinel~ field in org-pending-penreg
   object and instead implement that hard-coded ~update~ lambda from
   ~org-pending~ as a part of ~org-pending-region-update~.

3. I feel that different handling of "owner" and indirect buffers is not
   right.

   From the user perspective, it does not matter whether we run an src
   block from one or another indirect buffers - it makes sense to see
   the status in all the indirect org-mode buffers. Maybe we can hook
   into org-mode's fontification and display pending overlays in all the
   indirect buffers.

   Further, it is very confusing that running src block twice from the
   same buffer is not the same as running the same src block from one
   buffer and then from another indirect buffer. The current
   implementation of ~remove-previous-overlays~ makes such distinction
   for reasons I do not understand.

4. I have questions about ~handle-result~ argument in ~org-pending~.

   It is only called on success, but I can easily see that we need to
   handle things specially on failure as well. For example, insert
   stderr or perform other actions like displaying some buffer.

   Or we may even hook some special action to clicking on status
   overlay. For example, clicking on "failure" status overlay may raise
   stderr log.

-- 
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>