Comments (3)
I looked at the current definitions for:
Roughly, it looks to me like:
janet_call
callsrun_vm
(the main bytecode interpreter loop)janet_continue
callsjanet_continue_no_check
which in turn callsrun_vm
janet_dobytes
creates at least one fiber and then callsjanet_continue
janet_dostring
is a wrapper aroundjanet_dobytes
janet_pcall
sometimes creates a fiber (reuses an existing one in some cases) and then callsjanet_continue
Based on these observations and the original text, my current guess is that of the mentioned functions, janet_continue
is likely to be one of the more efficient options that doesn't involve GC suspension, while if suspending GC is not such a concern (presumably for "simple, short running logic"), then janet_call
is also a "more efficient option".
If confirmation is obtained on the above, I wouldn't be surprised if an appropriate PR for updating the text to explicitly mention these as "the more efficient options" got accepted.
from janet-lang.org.
Not sure what the text was like at the time of the original post.
Although janet_call
has the associated text:
Try to put mostly simple, short running logic here as this suspends the garbage collector for the duration of the call.
I don't see that kind of text for janet_continue
:
Resumes a new or suspended fiber. Returns a signal that corresponds to the status of the fiber after execution, and places the return/signal value in out. When resuming a fiber, the value to resume with should be in the argument in, which corresponds to the second argument to the Janet resume function.
nor for janet_pcall
:
Invoke a function in a protected manner, catching any panics raised. Returns the resulting status code, as well as placing the return value in *out. The fiber pointer f is a pointer to a fiber pointer will contain the fiber used to run the function fun. If f is NULL, a new fiber will be created. Otherwise, Janet will use the fiber pointed to by f to run fun.
If no panics are raised, will return JANET_SIGNAL_OK. If an error is raised, will return JANET_SIGNAL_ERROR. Other signals will be returned as expected.
May be it's one or both of these that was being hinted at?
from janet-lang.org.
I can't remember whether the text was any different at the time either. I do recall the janet_call
text contributing to the confusion and, more importantly, the following from janet_dobytes
:
Use this function to compile and run some Janet source code from C. If you plan on running the code multiple times, there are more efficient options. However, for code that will only run once, this is a useful function.
Perhaps the issue here is that "there are more efficient options" doesn't actually do anything to point the reader to those options; something as simple as naming them would suffice.
A few more points:
- By virtue of its name, I would expect
janet_call
to be the way of calling Janet code. Its "I'm the one you're looking for" name is contradicted by its documentation asking the user to restrict its usage to "mostly simple code, short running logic", causing some cognitive dissonance as to whether it's "the main one" or a "lightweight, restricted version". - Again by looking at just the name, one would expect
janet_pcall
to be a superset of, or otherwise very tightly coupled with,janet_call
(janet protected call
reads like "janet call
but with some extra steps for protection"). Ifjanet_pcall
is more efficient/capable of handling more complex logic thanjanet_call
, then that's not made clear by neither the name nor the documentation. janet_do_bytes
, by virtue of havingbytes
in its name, initially had me thinking that it's meant for evaluating code that has already been compiled to bytecode, which Janet clearly states it's capable of, reinforcing that initial impression. Since bytecode execution is generally expected to be faster than simply calling a not-yet-compiled string of code, then the statement "there are more efficient options" adds further dissonance.- One would not assume that
janet_continue
is the name of a procedure meant for running/calling code, but rather something to do with continuing execution.
I'm happy to discuss possible solutions to the above, but some would require changes to the method names in addition to amendments to the documentation. Is the project open to such changes?
from janet-lang.org.
Related Issues (20)
- Document on emscripten outdated HOT 3
- Auto-focusing search means you can't link to specific API functions HOT 1
- Example in "Installing a module" points at archived repository
- PEG specials `true` and `false` lack docs on PEG page HOT 2
- Related Windows instructions out-of-sync
- Bytecode reference table lacks entry for divf HOT 1
- Several (probably all) community examples links of spork functions are broken. HOT 9
- Bytecode reference table lacks entry for subim
- Non-ideal discoverability of Janet divergences from other programming languages HOT 9
- Extra dots in some operator symbols in ref table for abstract machine instructions?
- Document `&keys` better. HOT 12
- Document spork/utf8. HOT 4
- Document `init.janet` for `import`. HOT 2
- Document how to import an absolute path with `import`. HOT 8
- Document `declare-bin`. HOT 5
- Subprocess management appears under-documented HOT 2
- Identifiers with slashes / solidi can end up across multiple lines HOT 1
- The `split` PEG special lacks documentation
- Regarding keeping editor and tooling info on the front-page up-to-date HOT 15
- Docs don't mention that function literals can be named with keywords
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from janet-lang.org.