What does "inlined" mean? #1814
Comments
|
"Inlined" refers to code that has been directly inserted into a sequence of instructions rather than being referenced as a separate function. It’s a well-understood term in programming and compiler design, often associated with optimizing performance by avoiding the overhead of function calls. However, if clarity is a concern, "embedded inline" might be a better choice for broader audiences. I would suggest: "If embedded inline, the compare-and-swap functionality requires only four instructions." |
|
IMO, “inline” is a sufficiently common verb in the programming languages/compilers context that this sentence is fine as-is. |
|
"inlined" is not a word. I can infer meaning from it based on the common usage of "inline" but it doesn't change the fact that "inlined" is not a word! Additionally, the sentence has an unclear antecedent. You must infer that it is the code from the example that is to appear inline. Plus do all compare-and-swap functionalities that are embedded inline require only four instructions or just this example? Rather than make the reader infer meaning, we can make this section more clear with a few edits. We can, however, just remove the "d" from "inlined". It is a less effective fix, but one I can live with. |
|
It's common practice for technical documents to use terminology that's nonstandard in English but is standard within the technical domain. In this community, using "inlined" as a past-tense verb or as an adjective is without a doubt accepted: https://scholar.google.com/scholar?hl=en&as_sdt=0%2C5&q=inlined&btnG= Of course we could rewrite this one sentence, but I'd like to first understand the broader strategy. This document is chockablock with computer-science jargon. Rewriting the document to be entirely free of technical jargon would seem to me to be a questionable expenditure that would ultimately produce something that's less readable. |
|
I'm going to have to agree with Andrew here; the description of something
as "inlined" will be commonly understood by anyone who can understand the
rest of this document.
It's a software description that even I, as a hardware person, understand.
It refers to a function that is inserted directly into software instead of
being called as a subroutine.
Just wait until you get to "loop unrolling"....
…On Tue, Jan 21, 2025 at 7:09 AM Andrew Waterman ***@***.***> wrote:
It's common practice for technical documents to use terminology that's
nonstandard in English but is standard within the technical domain. In this
community, using "inlined" as a past-tense verb or as an adjective is
without a doubt accepted:
https://scholar.google.com/scholar?hl=en&as_sdt=0%2C5&q=inlined&btnG=
Of course we could rewrite this one sentence, but I'd like to first
understand the broader strategy. This document is chockablock with
computer-science jargon. Rewriting the document to be entirely free of
technical jargon would seem to me to be a questionable expenditure that
would ultimately produce something that's less readable.
—
Reply to this email directly, view it on GitHub
<#1814 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AHPXVJSAVNBPVEK4KSNUTLD2LZPKHAVCNFSM6AAAAABVMQBVE2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDMMBUHE4TENRQG4>
.
You are receiving this because you are subscribed to this thread.Message
ID: ***@***.***>
|
|
Let’s step back a bit. I have absolutely no problem with the word “inline”. It has a common meaning that even I understand! The word “inline” absolute has a place in technical documentation, including the RISC-V documents. In fact, in my first comment, my suggested rewrite includes the word “inline”. My objection is rather to the form “inlined”. We are moving towards becoming an ISO standard, which indicates the following spelling references: 8.2 Spelling reference works Spelling shall be consistent throughout a document. The following reference works for spelling are suggested: • for English, the Shorter Oxford English Dictionary, the Concise Oxford English Dictionary, the Collins Concise English Dictionary, the Webster’s New World College Dictionary or the Chambers Concise Dictionary; While “inline” appears in all of them, “inlined” does not. While I agree that this documentation is full of technical jargon, as it should since it is a technical document, I do think that we can make the language easier by rewriting some technical jargon into common word choices. |
|
I'm not trying to make a big deal out of "inlined". My only goal is to derive a general rule, since we're sure to run into this issue repeatedly. I respectfully disagree with your interpretation of that ISO directive. By my reading, its only requirement is consistency within a document. The references the directive mentions are only suggestions; there's no requirement that a word show up in one of them. |
|
I am not trying to make a big deal either! If the general rule you are trying to derive is that technical jargon is allowed, I'm all for that! For example, "virtualized" isn't found in most dictionaries. But I would never suggest removing it from technical documentation. Which is why I was asking for a definition of "inlined" just to make sure that I was not missing out on a specialized definition. I will try to be more clear in my requests in the future. I will also respectively point out that, if consistency is our goal, "inlined" appears one time in all of the priv and unpriv PDFs. Not sure of other docs such as debug. |
|
A (very) quick websearch results in "inlined" being primarily an adjective
("is inlined" or "an inlined function"),
overlapping with "inline" as a verb ("to inline a function") and also an
adjective ("an inline function is"
I'm not sure I can come up with a good rule when to use one rather than the
other, except on is defining the concept, and the other describes how it is
used?
Subject vs object maybe?
------------
How to guarantee that a function is inlined in C++
MSVC - Any way to check if function is actually inlined?
Identify whether a function is inlined in the LLVM IR
How do I know if a function has been inlined or not?
An inline function is one for which the compiler copies
How to check if a function is inlined or not?
ADMIN_IS_INLINED function - Determine if data is inlined
Perform better optimizations spanning the code the function is inlined into
that it normally couldn't perform across function boundaries.
... if the function the lambda is passed to is inlined, the return can be
inlined, as well.
------------
What does it mean to inline a function and how does it affect a program?
(IBM. https://www.ibm.com › support › pages › what-does-it-m...
inline Functions in C and C++
https://kotlinlang.org › ... › Functions › Inline functions
In computing, inline expansion, or inlining, is a manual or compiler
optimization <-- both forms in one sentence
In the C and C++ programming languages, an inline function is one qualified
with the keyword inline; this serves two purposes.
Inline parameters do not create bindings and are simply inlined. <-- both
forms in one sentence
…On Tue, Jan 21, 2025 at 12:35 PM Kersten Richter ***@***.***> wrote:
I am not trying to make a big deal either! If the general rule you are
trying to derive is that technical jargon is allowed, I'm all for that! For
example, "virtualized" isn't found in most dictionaries. But I would never
suggest removing it from technical documentation. Which is why I was asking
for a definition of "inlined" just to make sure that I was not missing out
on a specialized definition. I will try to be more clear in my requests in
the future.
I will also respectively point out that, if consistency is our goal,
"inlined" appears one time in all of the priv and unpriv PDFs. Not sure of
other docs such as debug.
—
Reply to this email directly, view it on GitHub
<#1814 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AHPXVJU4HB5KDQYIEAWVQT32L2VQTAVCNFSM6AAAAABVMQBVE2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDMMBVGY4DINZXGM>
.
You are receiving this because you commented.Message ID:
***@***.***>
|
|
A couple observations:
If we can agree on these three things, I feel like we can make progress. If not, I worry whether and how we will improve. |
Well said, I'll try to continue along these lines:
The ISO suggested dictionaries don't have "inline"; they only have different meanings of "inline", which makes them inapplicable. Similar cases in the future could be more conflicting if we choose dictionaries that do not keep pace with language evolution: here one side claimed "inline" (verb) is not a word while the other side understood it perfectly. For example following links from inlined can get a reader to an explanation of inlining. LLMs also give a good explanation.
As I see it, this more or less happened here. The "inline" (verb) has not been understood and the replacement phrase "embedded inline" was rejected because it's not a common expression for the intended meaning. There were a few tangents, but sharing ideas is not an easy process. |
|
Going to try one more time to explain this issue. The word we are discussing is "inlined". The sentence we are looking at is "If inlined, compare-and-swap functionality need only take four instructions." In this case, the word "inlined" is an adjective, describing the example code (as inferred from context - see original issue description for full passage). You can determine this by adding a noun to the sentence. You would not say "If the code inlined" but instead "If the code is inlined." So "code" is the noun, "inlined" is the adjective that is describing the code and "is" is the linking verb, connecting the noun to the adjective. So let's substitute another adjective, for example "blue". Because blue doesn't have any meaning really in the computer world, let's use a car as the noun. So "If blued, the car moves to the left." Okay so what does "blued" mean in this case? I can infer meaning from the base word "blue" and assume that for some specific reason, blue cars go left. But, this sentence occurs in highly technical information so I need to make sure that "blued" does not have any specialized meaning (and hence, I created the issue). However, it turns out that "blued" means the same as "blue". To bring it full circle, "inlined" has been determined to have the same meaning as "inline". So now we have what is basically a typo or new technical jargon. We can either fix this single use word by removing the "d" (and preferably adding a noun and linking verb) or we can set up a entry in our glossary and create a new word, complete with definition, as you should always do when introducing technical jargon, even sometimes with jargon that is commonly understood. Again, this new word in "inlined", which is a new word and not "inline", which is not. We can have a whole discussion about the verbification of nouns and adjectives, but it really isn't a best practice in technical documentation. |
|
"inlined" in that sentence is a past participle of the verb "inline". It is not productive to discuss solutions without agreeing on the issue... We want to make a precedent with a good explanation of the underlying cause. So far, I have no idea if the problem is one or more of the following:
|
|
I don't think we want to use Wiktionary as a technical reference. For example, "blued" is also defined in WIktionary. If we are trying to stick to the words found in the approved dictionaries, then "inline" is generally defined as an adjective. If the bad word in my rewrite is "embedded", then I have no problem removing it and changing to "If this example is inline". I'll even go for "If inline". Neither of these suggestions change the original meaning of the sentence. We generally do not use past tense in technical writing as a best practice anyway. |
|
Yes, that is the root of this issue. Dictionaries don't have the definition of "inline" that is used in this manual. For example Ada 22 (ISO/IEC 8652:2023) uses inlined:
Blindly copying others isn't good practice either, so if we look for alternatives, then "If expanded inline," is the most common one (I would never use it as it feels baroque, but it should be understandable). |
|
Before I add a few new thoughts, thanks to all who've been pushing this discussion forward in a productive manner. It may not feel like it, but we're making progress! As a good friend of mine said to me once, "It's not the result, it's the process which matters." It's funny how many situations that applies to in life... Returning to the problem at hand, I believe we need to agree upon our "rules", i.e one or more dictionaries. Any one we use should be freely available on-line so that we can use them and link to them to answer questions like "is inlined a word?" and "what part of speech is inlined?" Having these would allow us to use the same "rules" for this and similar issues. If we agree, I propose the @kersten1 and the Doc SIG take the AI to provide the "definitive" list and ensure we put it in our specification writer's guide (Authoring and Editing RISC-V Specifications). Secondly, I'd propose we should take this time clearly articulated process, in the writer's guide again, for handling our exceptions. Specifically, I'm interested in seeing the Where and the How? Although I think the Where is most simple (our Glossar), I'll be intrigued to see the How. For example, is the Doc SIG going to review and approve all proposed new words or are you going to let me decide (Mom would be so proud if you do). ;-) If we do these two things, we can all apply the rules and if we still feel we need to create an exception, we know what's needed. Then, we can complete our fun with inlined. |
In the 14.1. Specifying Ordering of Atomic Instructions section of the unpriv, there is a para that says this:
"LR/SC can be used to construct lock-free data structures. An example using LR/SC to implement a compare-and-swap function is shown in Example 2. If inlined, compare-and-swap functionality need only take four instructions."
Inlined isn't a word that I can find. Bill T pointed out that it is probably in reference to the inline assembler.
Can someone confirm that?
If so, Does this rewrite make sense?
"LR/SC can be used to construct lock-free data structures. The previous example shows LR/SC implementing a compare-and-swap function. If this example is embedded inline, the compare-and-swap functionality requires only four instructions."
The text was updated successfully, but these errors were encountered: