jiri/org-ql
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Docs: (Caching) Fix and clarify

Browse source
This commit is contained in:
Adam Porter 2020-11-23 04:48:35 -06:00
parent 27609264a5
commit 37c6f23297
2 changed files with 43 additions and 39 deletions
Download patch file Download diff file Expand all files Collapse all files

4
README.org
View file

@ -305,9 +305,9 @@ The variable =org-ql-block-header= may be bound to a string to use as the block
**** Caching **** Caching
Org QL uses a per-buffer cache to speed up subsequent searches. It's keyed on query expressions, which means that, for the same query in the same buffer, if the buffer has not been modified since the last time the query was run, the cached result will be returned, and the query will not be evaluated in that buffer again. Org QL uses a per-buffer cache to speed up subsequent searches. It's keyed on query expressions and match actions, which means that, for the same query and same match action in the same buffer, if the buffer has not been modified since the last time the query was run, the cached match-action result will be returned, and the query will not be evaluated in that buffer again.
Therefore, since query expressions are not guaranteed to be evaluated when these functions are called, they should be free of side effects. Any side effects should be done in the action expression instead. Therefore, since neither query expressions nor match actions are guaranteed to be evaluated when the following functions are called, they should be free of side effects. Or, if a side effect is required, the cache should be invalidated (e.g. by incrementing the buffer's modified tick, or by using a query expression or match action that has yet to be cached). /Note: Future improvements will allow the cache to be more easily disabled or cleared./
**** Function: ~org-ql-select~ **** Function: ~org-ql-select~

78
org-ql.info
View file

@ -617,15 +617,19 @@ File: README.info, Node: Listing / acting-on results, Next: Custom predicates,
1. Caching 1. Caching
Org QL uses a per-buffer cache to speed up subsequent searches. Org QL uses a per-buffer cache to speed up subsequent searches.
It’s keyed on query expressions, which means that, for the same It’s keyed on query expressions and match actions, which means
query in the same buffer, if the buffer has not been modified since that, for the same query and same match action in the same buffer,
the last time the query was run, the cached result will be if the buffer has not been modified since the last time the query
returned, and the query will not be evaluated in that buffer again. was run, the cached match-action result will be returned, and the
query will not be evaluated in that buffer again.
Therefore, since query expressions are not guaranteed to be Therefore, since neither query expressions nor match actions are
evaluated when these functions are called, they should be free of guaranteed to be evaluated when the following functions are called,
side effects. Any side effects should be done in the action they should be free of side effects. Or, if a side effect is
expression instead. required, the cache should be invalidated (e.g. by incrementing
the buffer’s modified tick, or by using a query expression or match
action that has yet to be cached). _Note: Future improvements will
allow the cache to be more easily disabled or cleared._
2. Function: ‘org-ql-select’ 2. Function: ‘org-ql-select’
@ -1457,35 +1461,35 @@ Node: Date/time predicates17382
Node: Functions / Macros20037 Node: Functions / Macros20037
Node: Agenda-like views20335 Node: Agenda-like views20335
Node: Listing / acting-on results21740 Node: Listing / acting-on results21740
Node: Custom predicates26961 Node: Custom predicates27281
Node: Dynamic block30452 Node: Dynamic block30772
Node: Links33150 Node: Links33470
Node: Tips33837 Node: Tips34157
Node: Changelog34155 Node: Changelog34475
Node: 06-pre34851 Node: 06-pre35171
Node: 0535291 Node: 0535611
Node: 04936768 Node: 04937088
Node: 04837042 Node: 04837362
Node: 04737389 Node: 04737709
Node: 04637784 Node: 04638104
Node: 04538184 Node: 04538504
Node: 04438543 Node: 04438863
Node: 04338900 Node: 04339220
Node: 04239095 Node: 04239415
Node: 04139256 Node: 04139576
Node: 0439497 Node: 0439817
Node: 03243430 Node: 03243750
Node: 03143809 Node: 03144129
Node: 0344006 Node: 0344326
Node: 02346981 Node: 02347301
Node: 02247209 Node: 02247529
Node: 02147477 Node: 02147797
Node: 0247676 Node: 0247996
Node: 0151711 Node: 0152031
Node: Notes51812 Node: Notes52132
Node: Comparison with Org Agenda searches51974 Node: Comparison with Org Agenda searches52294
Node: org-sidebar52846 Node: org-sidebar53166
Node: License53125 Node: License53445
 
End Tag Table End Tag Table