Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

devdocs notes on memory layout and runtime initialisation #9468

Merged
merged 8 commits into from
Feb 21, 2015

Conversation

samoconnor
Copy link
Contributor

Some notes I made while learning about runtime internals.
Maybe useful for other new developers.
But maybe misleading because eggnog :)

@tkelman
Copy link
Contributor

tkelman commented Dec 27, 2014

Very cool, thanks for writing these down! For reference, since it touches on related stuff (kinda), here's Jeff's talk from JuliaCon: https://www.youtube.com/watch?v=osdeT-tWjzk

@timholy
Copy link
Member

timholy commented Dec 27, 2014

I haven't looked at this in any detail whatsoever, but big +1 for doing this!

Next `parse_opts()
<https://github.com/JuliaLang/julia/blob/master/ui/repl.c#L80>`_
is called to process command line options. Note that parse_opts()
only deals with options that effect early initialisation. Other
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

how about affect code generation or early initialization?

}

Note that all objects are allocated in multiples of 8 bytes, so the
smallest object size is 16 bytes (8 byte type pointer + 8 bytes
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the smallest object should be 8 bytes (8 byte type pointer + 0 bytes data)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

:)
I guess that's strictly speaking true, but to my mind, an "object" that contains only type information and no data is not really an object, it's just a "meta-object".

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it's been given the name singleton and is optimized and used fairly heavily (nothing is a builtin type that uses this). thus it's a pretty important type for understanding codegen.cpp and cgutils.cpp.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good to know. Thx.
noted in latest commit.


.. sidebar:: `special case. <https://github.com/JuliaLang/julia/blob/master/src/jltypes.c#L2973>`_

The special singleton object :data:`nothing` is "void".
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the unique instance of any type without any fields is called a singleton. nothing::Void is an example, not a special-case.

@samoconnor
Copy link
Contributor Author

Hi All,
Is there any interest in merging this PR?
If not I'll close it.
Cheers,
Sam

@timholy
Copy link
Member

timholy commented Feb 2, 2015

I just took a glance.

One thing I noticed is that your line-number links are not to a specific commit, and will go stale as the code changes (more rapidly than the actual content they describe). One way you can prevent this is by hitting y when you're on the GitHub page with the source: it will generate a URL that includes the sha1 for current master.

Probably the easiest way to make that change would be by search-and-replace with your editor, after you try the y trick once to see how the URL is formed.

@samoconnor
Copy link
Contributor Author

Hi @timholy,
Re line-number links, see comment from Dec 28:
... I admit I was worried about the line-number URL links too as I pasted them into the doc. However, until github has a syntax for linking to a function definition I think it's better than nothing. My guess is that the line numbers will drift over time, but that at least the links will take the reader close enough to the right place that it's still useful. I considered the alternative of using a link to a fixed version of the file, but I decided that it is better that the reader sees the latest code if they are reading about internals. If they find an annoyingly bad link, they can fix it.

@timholy
Copy link
Member

timholy commented Feb 2, 2015

I guess my point is this: rather than saying (this from your first link),

Execution starts at main in julia/ui/repl.c

it might be better to say

Execution starts at main in julia/ui/repl.c

Those might look the same, but you'll see they already take you to separate places. The fact that I had to update the line numbers is both illustrative and irrelevant: the key thing is that the URL I provided is specific to a particular commit. (In case you can't click on the pencil icon and see the actual URL, it's https://github.com/JuliaLang/julia/blob/2f97c78baae7c4004f2cb0890e0ff521a3fac51a/ui/repl.c#L370-L373. Note the sha1, 2f97c78, refering to a particular commit.) That gives people who might be reading your documentation (1) a sense for which version of julia it was written for, (2) permalinks to code that match the content of what you're actually talking about, and (3) an easy way to compare two versions and see what's changed in the meantime. For someone who's learning this for the first time, it's presumably easier for people see the actual code you were referring to and then for them to find where that code moved to than it is for them to try to guess what used to be sitting at that position.

Like I said, you get such permalinks by hitting y when you're on the source-code page in GitHub. But for you probably the easiest thing would be to figure out which sha1 julia was at when you wrote the documentation, and do a search-replace so that all the links are current.

@samoconnor
Copy link
Contributor Author

I'm quite familiar with making links to a particular commit. In this case I decided not to...

Dec 28: I considered the alternative of using a link to a fixed version of the file, but I decided that it is better that the reader sees the latest code if they are reading about internals. If they find an annoyingly bad link, they can fix it.

timholy: For someone who's learning this for the first time, it's presumably easier for people see the actual code you were referring to and then for them to find where that code moved to than it is for them to try to guess what used to be sitting at that position.

Dec 28: ... until github has a syntax for linking to a function definition I think it's better than nothing.

These links are from text that describes one named function calling another named function. There is no guessing involved, if the link does not land on the right line, the referenced function definition will be easy to find in that file.

While I understand what you're saying about permalinks, I made a conscious choice to use links that are approximate, but I believe, better than nothing. The reality of URLs is that they go stale over time. Readers have encountered this before and have skills for dealing with it.

The way I see it...

Future Case 1: Links remain close enough that the reader can easily follow along in the code as they read the doc.
Action: do nothing.

Future Case 2: The links end up woefully wrong (Note: if things have changed a lot, the probably the call path that is described in the doc is also out of date).
Action: Delete the doc -- "this doc is too out of date to be useful"; or update the links --- "someone changed the code but forgot to update the docs"; or reduce the links to just pointing to the files -- "keeping these line-number links up to date turns out to be a pain, lets just link to the file".

I'm offering up these notes as-is in case they are useful. If they don't meet the standard required for doc/devdocs, maybe its better if I make a julia-dev post (that was my initial intention, but I thought they might be more easily discovered by the relevant audience in doc/devdocs).
Unfortunately, I am currently unable to spend more time on this.

@timholy
Copy link
Member

timholy commented Feb 21, 2015

Despite my concerns over the links, there's good material here. I'm inclined to merge, and then if some sections become too outdated to be useful, we can just delete them.

@ViralBShah
Copy link
Member

Go for it.

timholy added a commit that referenced this pull request Feb 21, 2015
devdocs notes on memory layout and runtime initialisation
@timholy timholy merged commit 65ddb08 into JuliaLang:master Feb 21, 2015
@timholy
Copy link
Member

timholy commented Feb 21, 2015

Thanks again, @samoconnor!

@@ -0,0 +1,88 @@
******************************
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@vtjnash reminder to self: correct this section in #7906

@tkelman
Copy link
Contributor

tkelman commented Aug 6, 2015

The line numbers in the links here are now failing linkcheck because much of the content of this file was reorganized. So we can either update all the line numbers or remove them.

@tkelman tkelman mentioned this pull request Aug 11, 2015
13 tasks
@tkelman
Copy link
Contributor

tkelman commented Sep 3, 2015

If no one wants to fix the line numbers in init.rst I'll be removing the code links.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

6 participants