Add list of cached functions #3599
Conversation
| @@ -0,0 +1,323 @@ | |||
| # Functions Which Cache Things | |||
|
|
|||
| Many functions take in a keyword argument `cached::Bool`, which then cache or do not cache the results of computations to make things faster. This can sometimes lead to strange behaviour. So we document all the functions which do this, and at a future date, maybe do something with this list. | |||
There was a problem hiding this comment.
"cache or do not cache the results of computations to make things faster"
I don't think this is what is happening here.
To my understanding there are two reasons for caching in OSCAR:
- Functions which do complex computations and cache the result (like
groebner_basisormaximal_order), so it does not need to be computed again. These functions usually do not have (maybe never have) acachedkeyword. - Constructors which add the constructed parent object to a global dictionary (= cache), so that if people construct the same polynomial ring or whatever twice, they get the identical ring and everything will just work. This is what the
cachedkeyword is for. (So it is not about speed but convenience.)
Please correct me, if I am wrong here.
There was a problem hiding this comment.
You might be completely right. For now, I've removed that, and just added a "FIXME". Someone more qualified than me will have to figure out how to best phrase that paragraph.
|
Can you adapt it so that the functions get put into code blocks (I.e. surrounded by backticks)? That should nice up the printing |
|
I added some description of the different ways 'caching' occurs in OSCAR (at least the ones I'm aware of), I hope you don't mind @aaruni96. |
| true | ||
| ``` | ||
| This is mainly intended for interactive use where this behaviour may be convenient. | ||
| However, the parent objects constructed in this way cannot be deleted (that is, garbage collected) as they are stored in the dictionary. |
There was a problem hiding this comment.
I believe this is wrong, at least this is what I understand from the WeakValueDict docstring in AbstractAlgebra
WeakValueDict()constructs a hash table where the values are weak
references to objects which may be garbage collected even when
used as values in a hash table.
There was a problem hiding this comment.
This is how I understood it from the OSCAR book.
But yes, apparently garbage collection works:
julia> Qx, x = QQ[:x]
(Univariate polynomial ring in x over QQ, x)
julia> Oscar.Nemo.FmpqPolyID
AbstractAlgebra.WeakValueDict{Symbol, QQPolyRing}(...):
:x => Univariate polynomial ring in x over QQ
julia> Qx = 0
0
julia> x = 0
0
julia> GC.gc()
julia> Oscar.Nemo.FmpqPolyID
AbstractAlgebra.WeakValueDict{Symbol, QQPolyRing}()
Conclusion: I'm not qualified either to write this documentation.
| > - `similar(f::PolyRingElem, R::fqPolyRepField, s::Symbol=var(parent(f)` | ||
| > - `similar(f::PolyRingElem, R::FqPolyRepField, s::Symbol=var(parent(f)` |
There was a problem hiding this comment.
@aaruni96 your magical pipe seems to cut off some function signatures like here. (Just saying. As long as we don't know what we do with this list, there is probably no point in debugging this.)
There was a problem hiding this comment.
I see, it cuts off at the first closing parenthesis. Its probably worth fixing, as it might be confusing later as to why something without cached seems to appear in the list.
I'll change the sed pattern.
|
So what should we do with this list? Put it somewhere? But it will get outdated quickly. Or put a program to generate the list somewhere? Or add another section to the "General" section of the OSCAR manual? Maybe in https://docs.oscar-system.org/dev/General/faq/ or a new section "Things to be aware of when using OSCAR" (which then could also mention we have our own matrix and integer types, which is right now in the FAQ) @micjoswig since you asked for this, would be good to hear from you what you'd prefer |
Addresses #3450