-
-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #190 from azriel91/doc/why-rust
- Loading branch information
Showing
87 changed files
with
3,904 additions
and
15 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,19 +1,19 @@ | ||
| !function(r,i){"use strict";var n,c="hljs-ln",u="hljs-ln-line",a="hljs-ln-n",h=/\r\n|\r|\n/g;function e(n){"interactive"===i.readyState||"complete"===i.readyState?t(n):r.addEventListener("DOMContentLoaded",function(){t(n)})}function t(n){try{var e,t=i.querySelectorAll("code.hljs,code.nohighlight");for(e in t)!t.hasOwnProperty(e)||t[e].classList.contains("nohljsln")||l(t[e],n)}catch(n){r.console.error("LineNumbers error: ",n)}}function l(n,e){"object"==typeof n&&r.setTimeout(function(){n.innerHTML=o(n,e)},0)}function o(n,e){var e={singleLine:function(n){return n.singleLine||!1}(e=(e=e)||{}),startFrom:function(n,e){var t=0;isFinite(e.startFrom)&&(t=e.startFrom);e=function(n,e){return n.hasAttribute(e)?n.getAttribute(e):null}(n,"data-ln-start-from");null!==e&&(t=function(n,e){return n&&(n=Number(n),isFinite(n))?n:e}(e,0));return t}(n,e)},n=n.innerHTML,t=function(n){return 0===n.length?[]:n.split(h)}(n);if(""===t[t.length-1].trim()&&t.pop(),1<t.length||e.singleLine){for(var r="",i=Math.trunc(Math.log10(t.length)),l=0,o=t.length;l<o;l++){var s="";t[l].includes("boring")&&(s="boring"),r+=`<div class="${u}" | ||
| !function(r,i){"use strict";var n,u="hljs-ln",a="hljs-ln-line",h="hljs-ln-n",d=/\r\n|\r|\n/g;function e(n){"interactive"===i.readyState||"complete"===i.readyState?t(n):r.addEventListener("DOMContentLoaded",function(){t(n)})}function t(n){try{var e,t=i.querySelectorAll("code.hljs,code.nohighlight");for(e in t)!t.hasOwnProperty(e)||t[e].classList.contains("nohljsln")||l(t[e],n)}catch(n){r.console.error("LineNumbers error: ",n)}}function l(n,e){"object"==typeof n&&r.setTimeout(function(){n.innerHTML=o(n,e)},0)}function o(n,e){var t,e={singleLine:function(n){return n.singleLine||!1}(e=(e=e)||{}),startFrom:function(n,e){var t=0;isFinite(e.startFrom)&&(t=e.startFrom);e=function(n,e){return n.hasAttribute(e)?n.getAttribute(e):null}(n,"data-ln-start-from");null!==e&&(t=function(n,e){return n&&(n=Number(n),isFinite(n))?n:e}(e,0));return t}(n,e)},n=n.innerHTML,r=function(n){return 0===n.length?[]:n.split(d)}(n);if(""===r[r.length-1].trim()&&r.pop(),1<r.length||e.singleLine){for(var i="",l=Math.trunc(Math.log10(r.length)),o=0,s=r.length;o<s;o++){var c="";r[o].includes("boring")&&(c="boring"),t=o<s-1?r[o]+"\n":0<r[o].length?r[o]:"\n",i+=`<div class="${a}" | ||
| ><div | ||
| class="${a} ${s}" | ||
| style="width: ${i}em;" | ||
| ></div>${0<t[l].length?t[l]:" "}</div>`}return`<div | ||
| class="${c}" | ||
| class="${h} ${c}" | ||
| style="width: ${l}em;" | ||
| ></div>${t}</div>`}return`<div | ||
| class="${u}" | ||
| style="counter-reset: line-number-count ${e.startFrom}" | ||
| >${r}</div>`}return n}r.hljs?(r.hljs.initLineNumbersOnLoad=e,r.hljs.lineNumbersBlock=l,r.hljs.lineNumbersValue=function(n,e){var t;if("string"==typeof n)return(t=document.createElement("code")).innerHTML=n,o(t,e)},(n=i.createElement("style")).type="text/css",n.innerHTML=` | ||
| .${c} { display: block; } | ||
| .${u} { counter-increment: line-number-count; } | ||
| .${a} { | ||
| >${i}</div>`}return n}r.hljs?(r.hljs.initLineNumbersOnLoad=e,r.hljs.lineNumbersBlock=l,r.hljs.lineNumbersValue=function(n,e){var t;if("string"==typeof n)return(t=document.createElement("code")).innerHTML=n,o(t,e)},(n=i.createElement("style")).type="text/css",n.innerHTML=` | ||
| .${u} { display: block; } | ||
| .${a} { counter-increment: line-number-count; } | ||
| .${h} { | ||
| display: inline-block; | ||
| text-align: right; | ||
| margin-right: 2.0rem; | ||
| } | ||
| .${a}:before { | ||
| .${h}:before { | ||
| content: counter(line-number-count); | ||
| } | ||
| `,i.getElementsByTagName("head")[0].appendChild(n),e()):r.console.error("highlight.js not detected!")}(window,document); |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,21 @@ | ||
| <div style=" | ||
| display: flex; | ||
| flex-wrap: wrap; | ||
| flex-direction: column; | ||
| justify-content: center; | ||
| align-items: center; | ||
| text-align: center; | ||
| height: 80vh; | ||
| "> | ||
| <div> | ||
| <object | ||
| type="image/svg+xml" | ||
| data="why_rust/rustacean-flat-happy.svg" | ||
| width="500"></object> | ||
| </div> | ||
| <div style="font-size: 3.5em; font-weight: bold;">Why Rust</div> | ||
| <div style="font-size: 2.5em;">Convince Me!</div> | ||
| <div style="height: 100px;"></div> | ||
| <div style="font-size: 2.0em;">Azriel Hoh</div> | ||
| <div style="font-size: 1.5em;">April 2024</div> | ||
| </div> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,12 @@ | ||
| <div style=" | ||
| display: flex; | ||
| flex-wrap: wrap; | ||
| height: 80vh; | ||
| justify-content: center; | ||
| align-content: center; | ||
| font-size: 2.0em; | ||
| "> | ||
|
|
||
| # 🚧 Constraints | ||
|
|
||
| </div> |
25 changes: 25 additions & 0 deletions
25
doc/src/learning_material/why_rust/constraints/constrained.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,25 @@ | ||
| # Constrained | ||
|
|
||
| <div style="display: flex; justify-content: center;"> | ||
|
|
||
| <object | ||
| type="image/svg+xml" | ||
| data="source_compile_executable.svg" | ||
| height="100"></object> | ||
| <small>[](https://azriel.im/dot_ix/?src=BYSwpgTghhDGwE8BcAoABGgzgewK5zCTQG8BfdNMADzFlwBcoAjAG0JPJQDtsATMAPpcoAWzCZUGHPljsARNIIA6CJjkVqtBszZE5muo1Zh13PoP6ZYEiotl71GA9uMOUZ-gLAjsAKxA2UngERIC8G4C7Oxo0hjrsoYC9O%2B5gvADm4pJYwbICXtEuumgA2nZgADSUeUZsALru9MDehLb0CGyBGGg8nvwAZlC4LPTtHRX00ER0qtgQALQADtggXPSQFE6pFmB9A0MZI9RjUBP4OLMLSysQKEA)</small> | ||
|
|
||
| </div> | ||
|
|
||
| ```rust | ||
| fn main() { | ||
| let a = 1; | ||
| a = a + 1; | ||
| println!("a is: {a}"); | ||
| } | ||
| ``` | ||
|
|
||
| <!-- | ||
| 1. Source needs to be compiled into an application. | ||
| 2. Only source that adheres to constraints will pass compilation. | ||
| 3. The application should be more correct. | ||
| --> |
19 changes: 19 additions & 0 deletions
19
doc/src/learning_material/why_rust/constraints/constrained_fixed.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,19 @@ | ||
| # Constrained - Fixed | ||
|
|
||
| <div style="display: flex; justify-content: center;"> | ||
|
|
||
| <object | ||
| type="image/svg+xml" | ||
| data="source_compile_executable.svg" | ||
| height="100"></object> | ||
| <small>[](https://azriel.im/dot_ix/?src=BYSwpgTghhDGwE8BcAoABGgzgewK5zCTQG8BfdNMADzFlwBcoAjAG0JPJQDtsATMAPpcoAWzCZUGHPljsARNIIA6CJjkVqtBszZE5muo1Zh13PoP6ZYEiotl71GA9uMOUZ-gLAjsAKxA2UngERIC8G4C7Oxo0hjrsoYC9O%2B5gvADm4pJYwbICXtEuumgA2nZgADSUeUZsALru9MDehLb0CGyBGGg8nvwAZlC4LPTtHRX00ER0qtgQALQADtggXPSQFE6pFmB9A0MZI9RjUBP4OLMLSysQKEA)</small> | ||
|
|
||
| </div> | ||
|
|
||
| ```rust | ||
| fn main() { | ||
| let mut a = 1; | ||
| a = a + 1; | ||
| println!("a is: {a}"); | ||
| } | ||
| ``` |
12 changes: 12 additions & 0 deletions
12
doc/src/learning_material/why_rust/constraints/constraints_in_rust.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,12 @@ | ||
| # Constraints in Rust | ||
|
|
||
| <div style="text-align: center;"> | ||
|
|
||
| <div style="font-size: 150px;">🔥</div> | ||
|
|
||
| <div style="font-size: 1.5em;"> | ||
|
|
||
| Rust has over 9000 [error codes](https://doc.rust-lang.org/stable/error_codes/error-index.html). | ||
|
|
||
| </div> | ||
| </div> |
23 changes: 23 additions & 0 deletions
23
doc/src/learning_material/why_rust/constraints/constraints_summary.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,23 @@ | ||
| # Constraints Summary | ||
|
|
||
| <div style="font-size: 1.5em;"> | ||
|
|
||
| 1. Constraints mark programs as invalid. | ||
|
|
||
| 2. Well designed constraints mark incorrect programs as invalid. | ||
|
|
||
| 3. Rust has strict constraints, so more incorrect programs are marked invalid. | ||
|
|
||
| --- | ||
|
|
||
| Switch from: | ||
|
|
||
| > "It's so hard to get anything to compile." | ||
| > <div style="font-size: 3.0em; vertical-align: -100%; text-align: right;">🫠</div> | ||
| to: | ||
|
|
||
| > "The compiler is doing so much work for me." | ||
| > <div style="font-size: 3.0em; vertical-align: -100%; text-align: right;">🙇♂️</div> | ||
| </div> |
17 changes: 17 additions & 0 deletions
17
doc/src/learning_material/why_rust/constraints/correct_programs.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,17 @@ | ||
| # Correct Programs | ||
|
|
||
| <div style="display: flex; justify-content: center;"> | ||
|
|
||
| <object | ||
| type="image/svg+xml" | ||
| data="correct_programs_venn.svg" | ||
| width="500"></object> | ||
| <small>[](https://azriel.im/dot_ix/?src=CYSwTgpgxgLiD2A7AXAAgG4THKBDANgFAAWIWuYUxAnsoaqgM7wBmMA7hRHQwwEa5gAfQCMaAN4BferwHCATBOm9UcoQGYlM-oKEAWLSrUBWQ7yjwwkWFsKJ4wCEMS4AthEY8mrDlzQAiAB4%2BAD4AQXx8VABlH05IQIB6UP8ZCytoGACAYUtrGGCwRJDYtniIQuLKkIAGADoaxpEAUlSdYTFUf1cQRkYQRABzVABuNtVdRS7GEVQAXjmmeXG1TS7EAFdIld0DLtwoKAgABzghneFTLrADiFS7BydHRihPGTVO-wuhKf9GYngW2AqA2jAqfCKITqEAAjhsCIwABQASm%2Ba38dXcMABwBR3z2-gG6AIIGBA2OGxg3yu-gsiFAcCQ9wgwEGHi8HyEQjUewA2h8ADQTYR6AC670mXJMaH5kyFJnF7Q0XPS%2BRlqyFqsy4oejiEEFc8AAVr0vMwyn5UIBeDcAvTtpPKZNCAUHIJR00IAZcldPw9XrWnqVe39wqEV09hGxBu4MkYMGo%2BHZ2lQ9j1jhYuC2MDeKgY-1wxycFnwljQkGAiYYEAAHjAbmgoBswMwwABaY7wAYwLCJllsoSp9P4TNeFRVmu4NCkYCORCJrU2ctMYh5gvwItgNCDSAQGcqc2%2BSDD3i5-NCQvFpj4XCdwhAA)</small> | ||
|
|
||
| </div> | ||
|
|
||
| <!-- | ||
| 1. Within the realm of all software, only a very small subset is correct. | ||
| 2. Often we produce hundreds of incorrect copies in our attempt to create the correct version. | ||
| 3. Constraints enforced by a compiler are one way to reduce the number of these incorrect copies. | ||
| --> |
93 changes: 93 additions & 0 deletions
93
doc/src/learning_material/why_rust/constraints/correct_programs_venn.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
26 changes: 26 additions & 0 deletions
26
doc/src/learning_material/why_rust/constraints/data_race.cs
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,26 @@ | ||
| using System; | ||
| using System.Threading; | ||
|
|
||
| public class Program { | ||
| class Data { | ||
| public int Value { get; set; } | ||
| } | ||
|
|
||
| public static void Main() { | ||
| Data data = new Data { Value = 0 }; | ||
|
|
||
| Action inc0 = () => { for (int i = 0; i < 50000; i++) { data.Value += 1; } }; | ||
| Action inc1 = () => { for (int i = 0; i < 50000; i++) { data.Value += 1; } }; | ||
|
|
||
| Thread thread0 = new Thread(new ThreadStart(inc0)); | ||
| Thread thread1 = new Thread(new ThreadStart(inc1)); | ||
|
|
||
| thread0.Start(); | ||
| thread1.Start(); | ||
|
|
||
| thread0.Join(); | ||
| thread1.Join(); | ||
|
|
||
| Console.WriteLine($"value: {data.Value}"); | ||
| } | ||
| } |
22 changes: 22 additions & 0 deletions
22
doc/src/learning_material/why_rust/constraints/data_race_1.rs
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,22 @@ | ||
| use std::thread; | ||
|
|
||
| #[derive(Debug)] | ||
| struct Data { | ||
| value: u32, | ||
| } | ||
|
|
||
| fn main() { | ||
| let mut data = Data { value: 0 }; | ||
| let data = &mut data; | ||
|
|
||
| let work_0 = || (0..50000).for_each(|_| data.value += 1); | ||
| let work_1 = || (0..50000).for_each(|_| data.value += 1); | ||
|
|
||
| let thread_0 = thread::spawn(work_0); | ||
| let thread_1 = thread::spawn(work_1); | ||
|
|
||
| thread_0.join().unwrap(); | ||
| thread_1.join().unwrap(); | ||
|
|
||
| println!("value: {}", data.value); | ||
| } |
43 changes: 43 additions & 0 deletions
43
doc/src/learning_material/why_rust/constraints/data_race_2.rs
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,43 @@ | ||
| use std::{ | ||
| sync::{Arc, Mutex}, | ||
| thread, | ||
| }; | ||
|
|
||
| #[derive(Debug)] | ||
| struct Data { | ||
| value: u32, | ||
| } | ||
|
|
||
| fn main() -> thread::Result<()> { | ||
| let data = Data { value: 0 }; | ||
| let arc_mutex = Arc::new(Mutex::new(data)); | ||
| let arc_mutex_0 = arc_mutex.clone(); | ||
| let arc_mutex_1 = arc_mutex.clone(); | ||
|
|
||
| let work_0 = move || { | ||
| (0..50000).for_each(|_| { | ||
| if let Ok(mut data) = arc_mutex_0.lock() { | ||
| data.value += 1; | ||
| } | ||
| }); | ||
| }; | ||
| let work_1 = move || { | ||
| (0..50000).for_each(|_| { | ||
| if let Ok(mut data) = arc_mutex_1.lock() { | ||
| data.value += 1; | ||
| } | ||
| }) | ||
| }; | ||
|
|
||
| let thread_0 = thread::spawn(work_0); | ||
| let thread_1 = thread::spawn(work_1); | ||
|
|
||
| thread_0.join()?; | ||
| thread_1.join()?; | ||
|
|
||
| if let Ok(Ok(data)) = Arc::try_unwrap(arc_mutex).map(Mutex::into_inner) { | ||
| println!("value: {}", data.value); | ||
| } | ||
|
|
||
| Ok(()) | ||
| } |
Oops, something went wrong.