From 0d8fa0095c742dae41e282c9cfe734a323924e0e Mon Sep 17 00:00:00 2001 From: kshyatt Date: Fri, 23 Dec 2016 15:27:51 -0800 Subject: [PATCH 1/2] Remove old TypeCheck.jl ref, add backticks and refs --- doc/src/manual/performance-tips.md | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/doc/src/manual/performance-tips.md b/doc/src/manual/performance-tips.md index 75adec530f037..f439abcbc5796 100644 --- a/doc/src/manual/performance-tips.md +++ b/doc/src/manual/performance-tips.md @@ -28,8 +28,9 @@ y = f(x::Int + 1) Writing functions is better style. It leads to more reusable code and clarifies what steps are being done, and what their inputs and outputs are. -**NOTE:** All code in the REPL is evaluated in global scope, so a variable defined and assigned -at toplevel will be a **global** variable. +!!! note + All code in the REPL is evaluated in global scope, so a variable defined and assigned + at toplevel will be a **global** variable. In the following REPL session: @@ -116,8 +117,8 @@ the performance of your code: `*.mem` files to see information about where those allocations occur. See [Memory allocation analysis](@ref). * `@code_warntype` generates a representation of your code that can be helpful in finding expressions that result in type uncertainty. See [`@code_warntype`](@ref) below. - * The [Lint](https://github.com/tonyhffong/Lint.jl) and [TypeCheck](https://github.com/astrieanna/TypeCheck.jl) - packages can also warn you of certain types of programming errors. + * The [Lint](https://github.com/tonyhffong/Lint.jl) + package can also warn you of certain types of programming errors. ## Avoid containers with abstract type parameters @@ -185,7 +186,7 @@ MyAmbiguousType `b` and `c` have the same type, yet their underlying representation of data in memory is very different. Even if you stored just numeric values in field `a`, the fact that the memory representation of a `UInt8` differs from a `Float64` also means that the CPU needs to handle them using two different -kinds of instructions. Since the required information is not available in the type, such decisions +kinds of instructions. Since the required information is not available in the type, such decisions have to be made at run-time. This slows performance. You can do better by declaring the type of `a`. Here, we are focused on the case where `a` might @@ -285,7 +286,7 @@ code_llvm(func,(MyType,)) For reasons of length the results are not shown here, but you may wish to try this yourself. Because the type is fully-specified in the first case, the compiler doesn't need to generate any code -to resolve the type at run-time. This results in shorter and faster code. +to resolve the type at run-time. This results in shorter and faster code. ### Avoid fields with abstract containers @@ -588,7 +589,7 @@ The second form is also often better style and can lead to more code reuse. This pattern is used in several places in the standard library. For example, see `hvcat_fill` in [abstractarray.jl](https://github.com/JuliaLang/julia/blob/master/base/abstractarray.jl), or -the `fill!` function, which we could have used instead of writing our own `fill_twos!`. +the [`fill!`](@ref) function, which we could have used instead of writing our own `fill_twos!`. Functions like `strange_twos` occur when dealing with data of uncertain type, for example data loaded from an input file that might contain either integers, floats, strings, or something else. @@ -802,7 +803,7 @@ first element to appear in a slice expression should be coupled with the inner-m ## Pre-allocating outputs -If your function returns an Array or some other complex type, it may have to allocate memory. +If your function returns an `Array` or some other complex type, it may have to allocate memory. Unfortunately, oftentimes allocation and its converse, garbage collection, are substantial bottlenecks. Sometimes you can circumvent the need to allocate memory on each function call by preallocating @@ -963,8 +964,9 @@ responses = [fetch(r) for r in refs] ``` The former results in a single network round-trip to every worker, while the latter results in -two network calls - first by the `@spawnat` and the second due to the `fetch` (or even a `wait`). -The `fetch`/`wait` is also being executed serially resulting in an overall poorer performance. +two network calls - first by the [`@spawnat`](@ref) and the second due to the [`fetch`](@ref) +(or even a [`wait`](@ref)). +The [`fetch`](@ref)/[`wait`](@ref) is also being executed serially resulting in an overall poorer performance. ## Fix deprecation warnings From 246936ff560eb01ba0f746eadfb02dc8f9d4f1c7 Mon Sep 17 00:00:00 2001 From: kshyatt Date: Fri, 23 Dec 2016 15:28:09 -0800 Subject: [PATCH 2/2] Misc more backticks and refs --- doc/src/manual/functions.md | 8 +++---- doc/src/manual/linear-algebra.md | 2 +- doc/src/manual/networking-and-streams.md | 4 ++-- doc/src/manual/packages.md | 2 +- doc/src/manual/parallel-computing.md | 28 ++++++++++++------------ doc/src/manual/workflow-tips.md | 4 ++-- 6 files changed, 24 insertions(+), 24 deletions(-) diff --git a/doc/src/manual/functions.md b/doc/src/manual/functions.md index 134cfd0934f86..fbab1d98f68ae 100644 --- a/doc/src/manual/functions.md +++ b/doc/src/manual/functions.md @@ -92,7 +92,7 @@ Of course, in a purely linear function body like `g`, the usage of `return` is p the expression `x + y` is never evaluated and we could simply make `x * y` the last expression in the function and omit the `return`. In conjunction with other control flow, however, `return` is of real use. Here, for example, is a function that computes the hypotenuse length of a right -triangle with sides of length *x* and *y*, avoiding overflow: +triangle with sides of length `x` and `y`, avoiding overflow: ```julia function hypot(x,y) @@ -111,7 +111,7 @@ end ``` There are three possible points of return from this function, returning the values of three different -expressions, depending on the values of *x* and *y*. The `return` on the last line could be omitted +expressions, depending on the values of `x` and `y`. The `return` on the last line could be omitted since it is the last expression. ## Operators Are Functions @@ -179,8 +179,8 @@ julia> function (x) (::#3) (generic function with 1 method) ``` -This creates a function taking one argument *x* and returning the value of the polynomial *x*^2 + -2*x* - 1 at that value. Notice that the result is a generic function, but with a compiler-generated +This creates a function taking one argument `x` and returning the value of the polynomial `x^2 + +2x - 1` at that value. Notice that the result is a generic function, but with a compiler-generated name based on consecutive numbering. The primary use for anonymous functions is passing them to functions which take other functions diff --git a/doc/src/manual/linear-algebra.md b/doc/src/manual/linear-algebra.md index a83b2f7eefa79..a9e487dafd6bf 100644 --- a/doc/src/manual/linear-algebra.md +++ b/doc/src/manual/linear-algebra.md @@ -15,7 +15,7 @@ of the standard library documentation. | `Cholesky` | [Cholesky factorization](https://en.wikipedia.org/wiki/Cholesky_decomposition) | | `CholeskyPivoted` | [Pivoted](https://en.wikipedia.org/wiki/Pivot_element) Cholesky factorization | | `LU` | [LU factorization](https://en.wikipedia.org/wiki/LU_decomposition) | -| `LUTridiagonal` | LU factorization for Tridiagonal matrices | +| `LUTridiagonal` | LU factorization for [Tridiagonal](@ref) matrices | | `UmfpackLU` | LU factorization for sparse matrices (computed by UMFPack) | | `QR` | [QR factorization](https://en.wikipedia.org/wiki/QR_decomposition) | | `QRCompactWY` | Compact WY form of the QR factorization | diff --git a/doc/src/manual/networking-and-streams.md b/doc/src/manual/networking-and-streams.md index d8720cb1479b6..0a2e251b15c1f 100644 --- a/doc/src/manual/networking-and-streams.md +++ b/doc/src/manual/networking-and-streams.md @@ -110,8 +110,8 @@ julia> print(STDOUT,0x61) ## IO Output Contextual Properties Sometimes IO output can benefit from the ability to pass contextual information into show methods. -The `IOContext` object provides this framework for associating arbitrary metadata with an IO object. -For example, `showcompact` adds a hinting parameter to the IO object that the invoked show method +The [`IOContext`](@ref) object provides this framework for associating arbitrary metadata with an IO object. +For example, [`showcompact`](@ref) adds a hinting parameter to the IO object that the invoked show method should print a shorter output (if applicable). ## Working with Files diff --git a/doc/src/manual/packages.md b/doc/src/manual/packages.md index c1f53410d7fc7..1330212215057 100644 --- a/doc/src/manual/packages.md +++ b/doc/src/manual/packages.md @@ -263,7 +263,7 @@ the package, so its requirements must be satisfied by whatever other package ver The combination of top-level requirements in `~/.julia/v0.6/REQUIRE` and the requirement of fixed packages are used to determine what should be installed. -You can also update only a subset of the installed packages, by providing arguments to the *Pkg.update* +You can also update only a subset of the installed packages, by providing arguments to the [`Pkg.update`](@ref) function. In that case, only the packages provided as arguments and their dependencies will be updated: diff --git a/doc/src/manual/parallel-computing.md b/doc/src/manual/parallel-computing.md index 48a7ca69c2b2b..22072071005d1 100644 --- a/doc/src/manual/parallel-computing.md +++ b/doc/src/manual/parallel-computing.md @@ -165,7 +165,7 @@ Starting Julia with `julia -p 2`, you can use this to verify the following: allow you to store an object of type `MyType` on process 2 even if `DummyModule` is not in scope on process 2. -You can force a command to run on all processes using the `@everywhere` macro. For example, `@everywhere` +You can force a command to run on all processes using the [`@everywhere`](@ref) macro. For example, `@everywhere` can also be used to directly define a function on all processes: ```julia @@ -308,7 +308,7 @@ end ``` This code will not initialize all of `a`, since each process will have a separate copy of it. -Parallel for loops like these must be avoided. Fortunately, [Shared Arrays](@ref man-shared-arrays) can be used +Parallel for loops like these must be avoided. Fortunately, [Shared Arrays](@ref man-shared-arrays) can be used to get around this limitation: ```julia @@ -418,8 +418,8 @@ when [`remotecall_fetch()`](@ref) is called. ## Channels -The section on Tasks in [Control Flow](@ref) discussed the execution of multiple functions in -a co-operative manner. `Channels` can be quite useful to pass data between running tasks, particularly +The section on [`Task`](@ref)s in [Control Flow](@ref) discussed the execution of multiple functions in +a co-operative manner. [`Channel`](@ref)s can be quite useful to pass data between running tasks, particularly those involving I/O operations. Examples of operations involving I/O include reading/writing to files, accessing web services, @@ -459,13 +459,13 @@ A channel can be visualized as a pipe, i.e., it has a write end and read end. to the maximum number of elements that can be held in the channel at any time. For example, `Channel(32)` creates a channel that can hold a maximum of 32 objects of any type. A `Channel{MyType}(64)` can hold up to 64 objects of `MyType` at any time. - * If a `Channel` is empty, readers (on a [`take!()`](@ref) call) will block until data is available. - * If a `Channel` is full, writers (on a [`put!()`](@ref) call) will block until space becomes available. + * If a [`Channel`](@ref) is empty, readers (on a [`take!()`](@ref) call) will block until data is available. + * If a [`Channel`](@ref) is full, writers (on a [`put!()`](@ref) call) will block until space becomes available. * [`isready()`](@ref) tests for the presence of any object in the channel, while [`wait()`](@ref) waits for an object to become available. - * A `Channel` is in an open state initially. This means that it can be read from and written to - freely via [`take!()`](@ref) and [`put!()`](@ref) calls. [`close()`](@ref) closes a `Channel`. - On a closed `Channel`, [`put!()`](@ref) will fail. For example: + * A [`Channel`](@ref) is in an open state initially. This means that it can be read from and written to + freely via [`take!()`](@ref) and [`put!()`](@ref) calls. [`close()`](@ref) closes a [`Channel`](@ref). + On a closed [`Channel`](@ref), [`put!()`](@ref) will fail. For example: ```julia julia> c=Channel(2); @@ -602,7 +602,7 @@ remote store. ## Channels and RemoteChannels - * A `Channel` is local to a process. Worker 2 cannot directly refer to a `Channel` on worker 3 and + * A [`Channel`](@ref) is local to a process. Worker 2 cannot directly refer to a `Channel` on worker 3 and vice-versa. A [`RemoteChannel`](@ref), however, can put and take values across workers. * A [`RemoteChannel`](@ref) can be thought of as a *handle* to a `Channel`. * The process id, `pid`, associated with a [`RemoteChannel`](@ref) identifies the process where @@ -858,7 +858,7 @@ function advection_shared!(q, u) end ``` -If we create SharedArrays and time these functions, we get the following results (with `julia -p 4`): +If we create `SharedArray`s and time these functions, we get the following results (with `julia -p 4`): ```julia q = SharedArray(Float64, (500,500,500)) @@ -1270,12 +1270,12 @@ All I/O tasks, timers, REPL commands, etc are multiplexed onto a single OS threa loop. A patched version of libuv ([http://docs.libuv.org/en/v1.x/](http://docs.libuv.org/en/v1.x/)) provides this functionality. Yield points provide for co-operatively scheduling multiple tasks onto the same OS thread. I/O tasks and timers yield implicitly while waiting for the event to -occur. Calling `yield()` explicitly allows for other tasks to be scheduled. +occur. Calling [`yield()`](@ref) explicitly allows for other tasks to be scheduled. -Thus, a task executing a `ccall` effectively prevents the Julia scheduler from executing any other +Thus, a task executing a [`ccall`](@ref) effectively prevents the Julia scheduler from executing any other tasks till the call returns. This is true for all calls into external libraries. Exceptions are calls into custom C code that call back into Julia (which may then yield) or C code that calls -`jl_yield()` (C equivalent of `yield()`). +`jl_yield()` (C equivalent of [`yield()`](@ref)). Note that while Julia code runs on a single thread (by default), libraries used by Julia may launch their own internal threads. For example, the BLAS library may start as many threads as there are diff --git a/doc/src/manual/workflow-tips.md b/doc/src/manual/workflow-tips.md index 37d742b26c20e..490139c103779 100644 --- a/doc/src/manual/workflow-tips.md +++ b/doc/src/manual/workflow-tips.md @@ -30,7 +30,7 @@ line. A common pattern includes the following elements: ``` and includes tests for the contents of `Tmp`. The value of using `import` versus `using` is that - you can call `reload``("Tmp")` instead of having to restart the REPL when your definitions change. + you can call `reload("Tmp")` instead of having to restart the REPL when your definitions change. Of course, the cost is the need to prepend `Tmp.` to uses of names defined in your module. (You can lower that cost by keeping your module name short.) @@ -45,7 +45,7 @@ line. A common pattern includes the following elements: end ``` - The advantage is that you can now do `using``Tmp` in your test code and can therefore avoid prepending + The advantage is that you can now do `using Tmp` in your test code and can therefore avoid prepending `Tmp.` everywhere. The disadvantage is that code can no longer be selectively copied to the REPL without some tweaking. * **Lather. Rinse. Repeat.** Explore ideas at the `julia` command prompt. Save good ideas in `tst.jl`.