From: Bruno Barbier <brubar.cs@gmail.com>
To: Ihor Radchenko <yantar92@posteo.net>
Cc: emacs-orgmode <emacs-orgmode@gnu.org>,
Jack Kamm <jackkamm@gmail.com>, Matt <matt@excalamus.com>
Subject: Re: Pending contents in org documents (Re: Asynchronous blocks for everything (was Re: ...))
Date: Thu, 04 Apr 2024 18:33:00 +0200 [thread overview]
Message-ID: <660ed63d.050a0220.36fdd.af23@mx.google.com> (raw)
In-Reply-To: <87le63c3qy.fsf@localhost>
Ihor Radchenko <yantar92@posteo.net> writes:
> Bruno Barbier <brubar.cs@gmail.com> writes:
>
>> I've pushed an update that should address most of your comments.
>
> Thanks!
>
>> I've found a better name: I'm now calling it a "lock". So I renamed
>> "PENREG" into "REGLOCK" as "region lock". The structure is now
>> `org-pending-reglock'.
>
> I slightly dislike short names and would prefer region-lock, but not a
> big deal - it is just my personal style preference.
It's more about being one word than being short, and being a new and
opaque word. REGLOCK is a new technical term; it's definition is the
cl-defstruct. For normal use, this is just a black box to pass
around.
I'll probably switch to using just "lock".
>> I've renamed org-pending-ti-send-update to org-pending-send-update
>> (now that the task control is gone, the prefix becomes useless).
>
> I have a further request on interaction with penreg objects.
> I feel that it is not ideal that overlays associated with penreg objects
> cannot be fully controlled by the callers.
I'm trying to limit the public API surface. I don't think we should
leak that we are currently using a mix of overlays and text
properties.
> In particular, I'd like to see some way to
>
> 1. Create penreg object without locking the region, so that scheduled-at
> time is not set immediately and status overlay is not displayed.
> Then, `org-pending-send-update' could send :schedule signal to
> perform actual lock.
Using the term "region" was confusing, sorry. That's why I switched
to region "lock". I don't think there is a use to create a lock that
doesn't lock.
Also, that might be tricky to implement: `org-pending-send-update' is
called asynchronously, from the user point of view. Having regions
that suddenly become locked, independently of what the user is
currently doing (if we implement the :schedule message), might be
difficult.
What use do you have in mind ?
> 2. Act on the outcome overlays - there is currently no way to remove
> them using penreg object.
I've added a funcion `org-pending-delete-outcome-marks' to manually
delete outcome marks that are in a given region.
Else, everything is handled automatically. Once the outcome is known,
the reglock is dead (not live-p). org-pending may leave outcome marks
about the outcomes (outcome marks are optional). The outcome marks
automatically disappear if the user remove the section, or, if a new
lock is created for the same region.
> Maybe :cancel signal? Canceled penreg
> objects can then be garbage-collected from the manager.
Cancel is handled by sending a failure message (see
`org-pending-cancel'). It's customizable using the reglock field
~org-pending-reglock-user-cancel-function~, which can decide what to
do (like kill a process) and which can send a better outcome.
Standard 'cancel' leaves a failure outcome mark.
I've added garbage collections of useless reglocks (success or
failure): see `org-pending--mgr-garbage-collect'.
> Also, the top-level commentary is getting incomplete and out-of-sync at
> this point. May you work towards more detailed top-level description of
> the library?
Sorry. I tried hard to keep it in sync with all the modifications.
I found it too much work, and, possibly overwhelming for the reader,
to explain everything in the top-level "Commentary" section.
That's why I deleted everything that wasn't mandatory to understand
the core features.
Everything should be documented as elisp documentation strings,
following the documentation of `org-pending' and
`org-pending-send-update', and, from code comments.
> May you work towards more detailed top-level description of
> the library?
> This will make your ideas more explicit and make life
> easier for me during the further review (now, I have to guess what you
> meant by some parts of the code).
Sorry, and thank you again for your time.
I tried to improve the overall documentation. I hope it's going to be
easier for you, and others.
>>> HANLDER will be another object we may expose via something like
>>> (org-pending-handler (&key on-success-function on-cancel-function on-await on-insert-logs) ...)
>>> Then, PENREG will call appropriate handler function as needed.
>>
>> As the task-control is now gone:
>> - get/await is gone,
>> - cancel is now a hook/function of REGLOCK,
>> - insert-details is now a hook/function too of REGLOCK.
>>> ...
>>> Yes. Lexical context is implicit and harder to debug, while storing
>>> necessary data explicitly in the struct slots is more robust as we are
>>> very clear which context is intended to be captured.
>>
>> Done.
>
> Is there any reason why you hide the extra information behind :-alist
> filed? Why not directly adding extra fields with proper documentation?
To hide them, indeed :)
The API for 'get-status and 'get-live-p are
`org-pending-reglock-status' and `org-pending-reglock-live-p' (they
are read-only). The API for the new `useless-p' is
`org-pending-reglock-useless-p' (it's read-only too).
The fields anchor-ovl, region-ovl, on-outcome, set-status and
creation-point are the dump of the closure context, so that
org-pending doesn't rely anymore on a closure to handle updates; I've
rewritten that recently. Nobody is supposed to use or change those
values, except the update process.
IMHO, dumping those as fields in the lock structure would be more
confusing and fragile than keeping those out of sight. I could add
comments when they are created/used in the code to help understand how
they are used.
I've added a new macro `org-pending-updating-region' that locks a
region while executing its body.
I've pushed a new version. The documentation in org-pending should
now be in sync, sorry.
Let me know what you think,
Thanks,
Bruno
next prev parent reply other threads:[~2024-04-04 16:34 UTC|newest]
Thread overview: 55+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-02-01 11:58 [BUG] Unexpected result when evaluating python src block asynchronously [9.7-pre (release_9.6.17-1131-gc9ed03.dirty @ /home/yantar92/.emacs.d/straight/build/org/)] Ihor Radchenko
2024-02-01 14:56 ` Bruno Barbier
2024-02-03 1:30 ` Jack Kamm
2024-02-04 15:07 ` Ihor Radchenko
2024-02-05 1:37 ` Jack Kamm
2024-02-05 14:29 ` Ihor Radchenko
2024-02-06 19:24 ` Bruno Barbier
2024-02-07 16:19 ` Ihor Radchenko
2024-02-07 17:40 ` Bruno Barbier
2024-02-08 3:21 ` Jack Kamm
2024-02-15 20:02 ` Asynchronous blocks for everything (was Re: [BUG] Unexpected result when evaluating python src block asynchronously [9.7-pre (release_9.6.17-1131-gc9ed03.dirty @ /home/yantar92/.emacs.d/straight/build/org/)]) Matt
2024-02-16 17:52 ` Bruno Barbier
2024-02-18 21:14 ` Matt
2024-02-19 0:31 ` Jack Kamm
2024-02-20 10:28 ` Ihor Radchenko
2024-02-20 10:46 ` tomas
2024-02-20 11:00 ` Ihor Radchenko
2024-02-20 11:03 ` tomas
2024-02-21 15:27 ` Bruno Barbier
[not found] ` <notmuch-sha1-61e086e33bd1faf1a123c1b0353cf2102c71bdac>
2024-02-28 10:18 ` Pending contents in org documents (Re: Asynchronous blocks for everything (was Re: ...)) Bruno Barbier
2024-03-02 10:03 ` Ihor Radchenko
2024-03-02 10:57 ` Bruno Barbier
2024-03-02 11:13 ` Ihor Radchenko
2024-03-02 18:06 ` Bruno Barbier
[not found] ` <notmuch-sha1-d2799a191385bf51811d7788856a83b4f5a1fe3b>
2024-03-07 17:08 ` Bruno Barbier
2024-03-07 18:29 ` Ihor Radchenko
2024-03-08 14:19 ` Bruno Barbier
2024-03-13 9:48 ` Ihor Radchenko
2024-03-19 9:33 ` Bruno Barbier
2024-03-20 10:23 ` Ihor Radchenko
2024-03-21 10:06 ` Bruno Barbier
2024-03-21 12:15 ` Ihor Radchenko
2024-03-25 17:46 ` Bruno Barbier
2024-03-27 11:29 ` Ihor Radchenko
2024-03-30 22:53 ` Rudolf Adamkovič
2024-04-04 16:35 ` Bruno Barbier
2024-04-04 16:33 ` Bruno Barbier [this message]
2024-04-11 11:44 ` Ihor Radchenko
2024-04-19 11:23 ` Bruno Barbier
2024-04-20 10:07 ` Ihor Radchenko
2024-02-19 0:15 ` Asynchronous blocks for everything (was Re: [BUG] Unexpected result when evaluating python src block asynchronously [9.7-pre (release_9.6.17-1131-gc9ed03.dirty @ /home/yantar92/.emacs.d/straight/build/org/)]) Jack Kamm
2024-02-21 15:43 ` Bruno Barbier
2024-02-19 9:06 ` Ihor Radchenko
2024-02-19 19:47 ` Matt
2024-02-19 20:10 ` Ihor Radchenko
2024-02-20 8:32 ` Ihor Radchenko
2024-02-20 17:04 ` Jack Kamm
2024-02-21 16:03 ` Bruno Barbier
2024-02-23 12:11 ` Ihor Radchenko
2024-02-23 13:24 ` Bruno Barbier
2024-02-24 11:59 ` Ihor Radchenko
2024-02-24 16:42 ` Bruno Barbier
2024-02-24 19:54 ` Matt
2024-02-28 10:21 ` Bruno Barbier
2024-02-08 3:26 ` [BUG] Unexpected result when evaluating python src block asynchronously [9.7-pre (release_9.6.17-1131-gc9ed03.dirty @ /home/yantar92/.emacs.d/straight/build/org/)] Jack Kamm
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=660ed63d.050a0220.36fdd.af23@mx.google.com \
--to=brubar.cs@gmail.com \
--cc=emacs-orgmode@gnu.org \
--cc=jackkamm@gmail.com \
--cc=matt@excalamus.com \
--cc=yantar92@posteo.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).