| ... | ... | @@ -718,6 +718,142 @@ test "init with undefined" { |
| 718 | 718 | {#header_close#} |
| 719 | 719 | {#header_close#} |
| 720 | 720 | {#header_close#} |
| 721 | |
| 722 | {#header_open|Variables#} |
| 723 | <p> |
| 724 | A variable is a unit of {#link|Memory#} storage. |
| 725 | </p> |
| 726 | <p> |
| 727 | Variables are never allowed to shadow identifiers from an outer scope. |
| 728 | </p> |
| 729 | <p> |
| 730 | It is generally preferable to use {#syntax#}const{#endsyntax#} rather than |
| 731 | {#syntax#}var{#endsyntax#} when declaring a variable. This causes less work for both |
| 732 | humans and computers to do when reading code, and creates more optimization opportunities. |
| 733 | </p> |
| 734 | {#header_open|Global Variables#} |
| 735 | <p> |
| 736 | Global variables are considered to be a top level declaration, which means that they are |
| 737 | order-independent and lazily analyzed. The initialization value of global variables is implicitly |
| 738 | {#link|comptime#}. If a global variable is {#syntax#}const{#endsyntax#} then its value is |
| 739 | {#syntax#}comptime{#endsyntax#}-known, otherwise it is runtime-known. |
| 740 | </p> |
| 741 | {#code_begin|test|global_variables#} |
| 742 | var y: i32 = add(10, x); |
| 743 | const x: i32 = add(12, 34); |
| 744 | |
| 745 | test "global variables" { |
| 746 | assert(x == 46); |
| 747 | assert(y == 56); |
| 748 | } |
| 749 | |
| 750 | fn add(a: i32, b: i32) i32 { |
| 751 | return a + b; |
| 752 | } |
| 753 | |
| 754 | const std = @import("std"); |
| 755 | const assert = std.debug.assert; |
| 756 | {#code_end#} |
| 757 | <p> |
| 758 | Global variables may be declared inside a {#link|struct#}, {#link|union#}, or {#link|enum#}: |
| 759 | </p> |
| 760 | {#code_begin|test|namespaced_global#} |
| 761 | const std = @import("std"); |
| 762 | const assert = std.debug.assert; |
| 763 | |
| 764 | test "namespaced global variable" { |
| 765 | assert(foo() == 1235); |
| 766 | assert(foo() == 1236); |
| 767 | } |
| 768 | |
| 769 | fn foo() i32 { |
| 770 | const S = struct { |
| 771 | var x: i32 = 1234; |
| 772 | }; |
| 773 | S.x += 1; |
| 774 | return S.x; |
| 775 | } |
| 776 | {#code_end#} |
| 777 | <p> |
| 778 | The {#syntax#}extern{#endsyntax#} keyword can be used to link against a variable that is exported |
| 779 | from another object. The {#syntax#}export{#endsyntax#} keyword or {#link|@export#} builtin function |
| 780 | can be used to make a variable available to other objects at link time. In both cases, |
| 781 | the type of the variable must be C ABI compatible. |
| 782 | </p> |
| 783 | {#see_also|Exporting a C Library#} |
| 784 | {#header_close#} |
| 785 | |
| 786 | {#header_open|Thread Local Variables#} |
| 787 | <p>A variable may be specified to be a thread-local variable using the |
| 788 | {#syntax#}threadlocal{#endsyntax#} keyword:</p> |
| 789 | {#code_begin|test|tls#} |
| 790 | const std = @import("std"); |
| 791 | const assert = std.debug.assert; |
| 792 | |
| 793 | threadlocal var x: i32 = 1234; |
| 794 | |
| 795 | test "thread local storage" { |
| 796 | const thread1 = try std.os.spawnThread({}, testTls); |
| 797 | const thread2 = try std.os.spawnThread({}, testTls); |
| 798 | testTls({}); |
| 799 | thread1.wait(); |
| 800 | thread2.wait(); |
| 801 | } |
| 802 | |
| 803 | fn testTls(context: void) void { |
| 804 | assert(x == 1234); |
| 805 | x += 1; |
| 806 | assert(x == 1235); |
| 807 | } |
| 808 | {#code_end#} |
| 809 | <p> |
| 810 | For {#link|Single Threaded Builds#}, all thread local variables are treated as {#link|Global Variables#}. |
| 811 | </p> |
| 812 | <p> |
| 813 | Thread local variables may not be {#syntax#}const{#endsyntax#}. |
| 814 | </p> |
| 815 | {#header_close#} |
| 816 | |
| 817 | {#header_open|Local Variables#} |
| 818 | <p> |
| 819 | Local variables occur inside {#link|Functions#}, {#link|comptime#} blocks, and {#link|@cImport#} blocks. |
| 820 | </p> |
| 821 | <p> |
| 822 | When a local variable is {#syntax#}const{#endsyntax#}, it means that after initialization, the variable's |
| 823 | value will not change. If the initialization value of a {#syntax#}const{#endsyntax#} variable is |
| 824 | {#link|comptime#}-known, then the variable is also {#syntax#}comptime{#endsyntax#}-known. |
| 825 | </p> |
| 826 | <p> |
| 827 | A local variable may be qualified with the {#syntax#}comptime{#endsyntax#} keyword. This causes |
| 828 | the variable's value to be {#syntax#}comptime{#endsyntax#}-known, and all loads and stores of the |
| 829 | variable to happen during semantic analysis of the program, rather than at runtime. |
| 830 | All variables declared in a {#syntax#}comptime{#endsyntax#} expression are implicitly |
| 831 | {#syntax#}comptime{#endsyntax#} variables. |
| 832 | </p> |
| 833 | {#code_begin|test|comptime_vars#} |
| 834 | const std = @import("std"); |
| 835 | const assert = std.debug.assert; |
| 836 | |
| 837 | test "comptime vars" { |
| 838 | var x: i32 = 1; |
| 839 | comptime var y: i32 = 1; |
| 840 | |
| 841 | x += 1; |
| 842 | y += 1; |
| 843 | |
| 844 | assert(x == 2); |
| 845 | assert(y == 2); |
| 846 | |
| 847 | if (y != 2) { |
| 848 | // This compile error never triggers because y is a comptime variable, |
| 849 | // and so `y != 2` is a comptime value, and this if is statically evaluated. |
| 850 | @compileError("wrong y value"); |
| 851 | } |
| 852 | } |
| 853 | {#code_end#} |
| 854 | {#header_close#} |
| 855 | {#header_close#} |
| 856 | |
| 721 | 857 | {#header_open|Integers#} |
| 722 | 858 | {#header_open|Integer Literals#} |
| 723 | 859 | {#code_begin|syntax#} |
| ... | ... | @@ -7568,7 +7704,7 @@ pub fn build(b: *Builder) void { |
| 7568 | 7704 | {#header_open|Single Threaded Builds#} |
| 7569 | 7705 | <p>Zig has a compile option <code>--single-threaded</code> which has the following effects: |
| 7570 | 7706 | <ul> |
| 7571 | | <li>Variables which have Thread Local Storage instead become globals.</li> |
| 7707 | <li>All {#link|Thread Local Variables#} are treated as {#link|Global Variables#}.</li> |
| 7572 | 7708 | <li>The overhead of {#link|Coroutines#} becomes equivalent to function call overhead. |
| 7573 | 7709 | TODO: please note this will not be implemented until the upcoming Coroutine Rewrite</li> |
| 7574 | 7710 | <li>The {#syntax#}@import("builtin").single_threaded{#endsyntax#} becomes {#syntax#}true{#endsyntax#} |
Andrew Kelley <andrew@ziglang.org> 2019-04-04 12:26:47-04:00
Commit is signed but in an unrecognized format.