Skip to content

Commit

Permalink
docs should only point to current stable jlcall.m version, since in…
Browse files Browse the repository at this point in the history
… general `master` version may not work for installed MATDaemon.jl
  • Loading branch information
jondeuce committed Oct 17, 2023
1 parent ab87586 commit b6ccfeb
Show file tree
Hide file tree
Showing 3 changed files with 21 additions and 21 deletions.
30 changes: 15 additions & 15 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Call Julia from MATLAB using a Julia daemon launched by [`DaemonMode.jl`](https:

## Quickstart

Use the MATLAB function [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/master/api/jlcall.m) to call Julia from MATLAB:
Use the MATLAB function [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/v0.1.3/api/jlcall.m) to call Julia from MATLAB:

```matlab
>> jlcall('sort', {rand(2,5)}, struct('dims', int64(2)))
Expand All @@ -21,13 +21,13 @@ ans =
0.0975 0.5469 0.9058 0.9134 0.9649
```

The positional arguments passed to [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/master/api/jlcall.m) are:
The positional arguments passed to [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/v0.1.3/api/jlcall.m) are:
1. The Julia function to call, given as a MATLAB `char` array. This can be any Julia expression which evaluates to a function. For example, `'a=2; b=3; x -> a*x+b'`. For convenience, the empty string `''` is interpreted as `'(args...; kwargs...) -> nothing'`, returning `nothing` for any inputs. **Note:** expressions are wrapped in a `let` block and evaluated in the global scope
2. Positional arguments, given as a MATLAB `cell` array. For example, `args = {arg1, arg2, ...}`
3. Keyword arguments, given as a MATLAB `struct`. For example, `kwargs = struct('key1', value1, 'key2', value2, ...)`

The first time [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/master/api/jlcall.m) is invoked:
1. `MATDaemon.jl` will be installed into a local Julia project, if one does not already exist. By default, a folder `.jlcall` is created in the same folder as [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/master/api/jlcall.m)
The first time [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/v0.1.3/api/jlcall.m) is invoked:
1. `MATDaemon.jl` will be installed into a local Julia project, if one does not already exist. By default, a folder `.jlcall` is created in the same folder as [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/v0.1.3/api/jlcall.m)
2. A Julia server will be started in the background using [`DaemonMode.jl`](https://github.com/dmolina/DaemonMode.jl)

All subsequent calls to Julia are run on the Julia server.
Expand Down Expand Up @@ -55,7 +55,7 @@ run [setup scripts](https://github.com/jondeuce/MATDaemon.jl#loading-setup-code)
[import modules](https://github.com/jondeuce/MATDaemon.jl#loading-setup-code) for later use,
or set the [number of threads](https://github.com/jondeuce/MATDaemon.jl#julia-multithreading) for running multithreaded code.

This setup can be conveniently executed at the start of your MATLAB script with a single call to [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/master/api/jlcall.m) as follows:
This setup can be conveniently executed at the start of your MATLAB script with a single call to [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/v0.1.3/api/jlcall.m) as follows:

```matlab
>> jlcall('', ...
Expand Down Expand Up @@ -104,7 +104,7 @@ ans =

### Persistent environments

By default, previously loaded Julia code is available on subsequent calls to [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/master/api/jlcall.m).
By default, previously loaded Julia code is available on subsequent calls to [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/v0.1.3/api/jlcall.m).
For example, following the [above call](https://github.com/jondeuce/MATDaemon.jl#loading-modules) to `LinearAlgebra.norm`, the `LinearAlgebra.det` function can be called without loading `LinearAlgebra` again:

```matlab
Expand Down Expand Up @@ -136,9 +136,9 @@ Stacktrace:

### Unique Julia instances

Instead of running Julia code on a persistent Julia server, unique Julia instances can be launched for each call to [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/master/api/jlcall.m) by passing the `'server'` flag with value `false`.
Instead of running Julia code on a persistent Julia server, unique Julia instances can be launched for each call to [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/v0.1.3/api/jlcall.m) by passing the `'server'` flag with value `false`.

**Note:** this may cause significant overhead when repeatedly calling [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/master/api/jlcall.m) due to Julia package precompilation and loading:
**Note:** this may cause significant overhead when repeatedly calling [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/v0.1.3/api/jlcall.m) due to Julia package precompilation and loading:

```matlab
>> tic; jlcall('x -> sum(abs2, x)', {1:5}, 'server', false); toc
Expand Down Expand Up @@ -176,7 +176,7 @@ One possible remedy is to define a wrapper function in a Julia script:
julia_version() = string(Base.VERSION)
```

Then, use the `'setup'` flag to pass the above script to [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/master/api/jlcall.m):
Then, use the `'setup'` flag to pass the above script to [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/v0.1.3/api/jlcall.m):

```matlab
>> jlcall('julia_version', 'setup', '/path/to/setup.jl')
Expand All @@ -189,7 +189,7 @@ ans =
In this case, `jlcall('() -> string(Base.VERSION)')` would work just as well.
In general, however, interfacing with complex Julia libraries using MATLAB types may be nontrivial, and the `'setup'` flag allows for the execution of arbitrary setup code.

**Note:** the setup script is loaded into the global scope using `include`; when using [persistent environments](https://github.com/jondeuce/MATDaemon.jl#persistent-environments), symbols defined in the setup script will be available on subsequent calls to [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/master/api/jlcall.m).
**Note:** the setup script is loaded into the global scope using `include`; when using [persistent environments](https://github.com/jondeuce/MATDaemon.jl#persistent-environments), symbols defined in the setup script will be available on subsequent calls to [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/v0.1.3/api/jlcall.m).

### Handling Julia outputs

Expand Down Expand Up @@ -238,9 +238,9 @@ In case the Julia server gets into a bad state, the following troubleshooting ti
* Try restarting the server: `jlcall(..., 'restart', true)`
* Enable debug mode for verbose logging: `jlcall(..., 'debug', true)`
* Call Julia directly instead of calling the server: `jlcall(..., 'server', false)`
* This will be slower, since each call to [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/master/api/jlcall.m) will start a new Julia instance, but it may [fix server issues on Windows](https://github.com/jondeuce/MATDaemon.jl/issues/9#issuecomment-1761710048)
* This will be slower, since each call to [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/v0.1.3/api/jlcall.m) will start a new Julia instance, but it may [fix server issues on Windows](https://github.com/jondeuce/MATDaemon.jl/issues/9#issuecomment-1761710048)
* Reinitialize the `MATDaemon.jl` workspace folder: `jlcall(..., 'reinstall', true)`
* By default, the workspace folder is named `.jlcall` and is stored in the same directory as [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/master/api/jlcall.m)
* By default, the workspace folder is named `.jlcall` and is stored in the same directory as [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/v0.1.3/api/jlcall.m)
* The `'reinstall'` flag deletes the workspace folder, forcing `MATDaemon.jl` to be reinstalled; you can also delete it manually

### Performance
Expand All @@ -251,13 +251,13 @@ Pointing these files to a ram-backed file system is recommended when possible (f
This is now the default; `'infile'` and `'outfile'` are created via the MATLAB `tempname` function (thanks to @mauro3 for this tip).

Nevertheless, this naturally leads to some overhead when calling Julia, particularly when the MATLAB inputs and/or Julia outputs have large memory footprints.
It is therefore not recommended to use [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/master/api/jlcall.m) in performance critical loops.
It is therefore not recommended to use [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/v0.1.3/api/jlcall.m) in performance critical loops.

## MATLAB and Julia version compatibility

This package has been tested on a variety of MATLAB versions.
However, for some versions of Julia and MATLAB, supported versions of external libraries may clash.
For example, running [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/master/api/jlcall.m) using Julia v1.6.1 and MATLAB R2015b gives the following error:
For example, running [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/v0.1.3/api/jlcall.m) using Julia v1.6.1 and MATLAB R2015b gives the following error:

```matlab
>> jlcall
Expand All @@ -275,4 +275,4 @@ If you encounter this issue, see the [`Julia`](https://github.com/JuliaLang/juli

This repository contains utilities for parsing and running Julia code, passing MATLAB arguments to Julia, and retrieving Julia outputs from MATLAB.

The workhorse behind `MATDaemon.jl` and [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/master/api/jlcall.m) is [`DaemonMode.jl`](https://github.com/dmolina/DaemonMode.jl) which is used to start a persistent Julia server in the background.
The workhorse behind `MATDaemon.jl` and [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/v0.1.3/api/jlcall.m) is [`DaemonMode.jl`](https://github.com/dmolina/DaemonMode.jl) which is used to start a persistent Julia server in the background.
2 changes: 1 addition & 1 deletion docs/src/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

!!! note
Manual installation of `MATDaemon.jl` is generally not necessary.
Simply download the [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/master/api/jlcall.m) MATLAB API function and `MATDaemon.jl` will be automatically installed into a local Julia project on first use.
Simply download the [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/v0.1.3/api/jlcall.m) MATLAB API function and `MATDaemon.jl` will be automatically installed into a local Julia project on first use.

## [Docstrings](@id docstrings)

Expand Down
10 changes: 5 additions & 5 deletions src/MATDaemon.jl
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ The destination `filename` can be overwritten if it exists by passing `force = t
"""
function download_jlcall(filename::String = joinpath(pwd(), "jlcall.m"); latest::Bool = false, force::Bool = false)
if latest
jlcall_github = "https://raw.githubusercontent.com/jondeuce/MATDaemon.jl/master/api/jlcall.m"
jlcall_github = "https://raw.githubusercontent.com/jondeuce/MATDaemon.jl/v$(VERSION)/api/jlcall.m"
jlcall_local = download(jlcall_github)
else
jlcall_local = normpath(@__DIR__, "../api/jlcall.m")
Expand Down Expand Up @@ -65,7 +65,7 @@ juliafy_kwargs(xs::Dict{String, Any}) = Pair{Symbol, Any}[Symbol(k) => v for (k,
"""
JLCallOptions(; kwargs...)
Julia struct for storing [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/master/api/jlcall.m) input parser results.
Julia struct for storing [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/v$(VERSION)/api/jlcall.m) input parser results.
Struct fields/keyword arguments for constructor:
Expand Down Expand Up @@ -154,7 +154,7 @@ end
"""
$(TYPEDSIGNATURES)
Load [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/master/api/jlcall.m) input parser results from `workspace`.
Load [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/v$(VERSION)/api/jlcall.m) input parser results from `workspace`.
"""
function load_options(workspace::String)
clean_value(k, v) =
Expand Down Expand Up @@ -220,7 +220,7 @@ end
"""
$(TYPEDSIGNATURES)
Run Julia function `f` using [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/master/api/jlcall.m) input parser results `opts`.
Run Julia function `f` using [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/v$(VERSION)/api/jlcall.m) input parser results `opts`.
"""
function jlcall(f::F, opts::JLCallOptions) where {F}
# Since `f` is dynamically defined in a global scope, try to force specialization on `f` (may help performance)
Expand All @@ -238,7 +238,7 @@ end
"""
$(TYPEDSIGNATURES)
Location of script for loading code, importing modules, and evaluating the function expression passed from [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/master/api/jlcall.m).
Location of script for loading code, importing modules, and evaluating the function expression passed from [`jlcall.m`](https://github.com/jondeuce/MATDaemon.jl/blob/v$(VERSION)/api/jlcall.m).
"""
jlcall_script() = joinpath(@__DIR__, "..", "api", "jlcall.jl")

Expand Down

0 comments on commit b6ccfeb

Please sign in to comment.