Reference

XPA.Client

An instance of the mutable structure XPA.Client represents a client connection in the XPA Messaging System.

XPA.connection()

yields a persistent XPA client connection that is kept open for the calling task (a different connection is memorized for each Julia task).

Per-task client connections are automatically open (or even re-open) and closed as needed.

XPA.get([T, [dims,]] [conn,] apt, args...; kwds...)

retrieves data from one or more XPA access-points apt with arguments args.... Argument apt is an instance of XPA.AccessPoint, a template name, a host:port string, or the path to a Unix socket file. Arguments args... are converted into a single string with elements of args... separated by a single space. Optional argument conn is a persistent XPA client connection created by XPA.Client; if omitted, a per-task connection is used (see XPA.connection). The returned value depends on the optional arguments T and dims.

If neither T nor dims are specified, an instance of XPA.Reply is returned with all the answer(s) from the XPA server(s).

If T and, possibly, dims are specified, a single answer and no errors are expected (as if nmax=1 and throwerrors=true) and the data part of the answer is converted according to T which must be a type and dims which is an optional array size:

• With dims an N-dimensional array size and T an array type like Array{S} or Array{S,N}, the data is returned as an array of this type and size.

• Without dims and if T is a vector type like Vector{S} or Memory{S}, the data is returned as a vector of type T with as many elements of type S that fit into the data.

• Without dims and if T is String, a string interpreting the data as ASCII characters is returned.

• Without dims and for any other types T, the sizeof(T) leading bytes of the data are returned as a single value of type T.

Except if T is String, trailing data bytes, if any, are ignored.

Keywords

• Keyword nmax specifies the maximum number of answers. Specify nmax=-1 to use the maximum number of XPA hosts. This keyword is forced to be 1 if T is specified; otherwise, nmax=1 by default.

• Keyword throwerrors specifies whether to check for errors. If this keyword is set true, an exception is thrown for the first error message encountered in the list of answers. This keyword is forced to be true if T is specified; otherwise, throwerrors is false by default.

• Keyword mode specifies options in the form "key1=value1,key2=value2".

• Keyword users specifies the list of possible users owning the access-point. This (temporarily) overrides the settings in environment variable XPA_NSUSERS. By default and if the environment variable XPA_NSUSERS is not set, the access-point must be owned the caller (see Section Distinguishing Users in XPA documentation). The value is a string which may be a list of comma separated user names or "*" to access all users on a given machine.

See also

XPA.Client, XPA.get_data, XPA.set, and XPA.verify.

XPA.Reply

type of structure used to store the answer(s) of XPA.get and XPA.set requests.

Assuming A is an instance of XPA.Reply, it can be used as an abstract vector and A[i] yields the i-th answer in A. The syntax A[] yields A[1] if A has a single answer and throws otherwise.

A single answer A[i] implements the following properties:

A[i].server       # identifier of the XPA server which sent the `i`-th answer
A[i].data(...)    # data associated with `i`-th answer (see below)
A[i].has_message  # whether `i`-th answer contains a message
A[i].has_error    # whether `i`-th answer has an error
A[i].message      # message or error message associated with `i`-th answer

To retrieve the data associated with a reply, the data property can be used as follows:

A[i].data()                  # a vector of bytes
A[i].data(String)            # a single ASCII string
A[i].data(T)                 # a single value of type `T`
A[i].data(Vector{T})         # the largest possible vector with elements of type `T`
A[i].data(Array{T}, dims...) # an array of element type `T` and size `dims...`

If Base.Memory exists Vector{T} can be replaced by Memory{T}.

See also

XPA.get, XPA.set, and XPA.has_errors.

XPA.get_data([T, [dims,]] rep::XPA.Reply, i=1; take=false)
XPA.get_data([T, [dims,]] rep[i]; take=false)
rep[i].data([T, [dims,]]; take=false)

yields the data associated with the i-th answer in XPA reply rep. The returned value depends on the optional leading arguments T and dims:

• If neither T nor dims are specified, the data is returned as a vector of bytes (UInt8).

• With dims an N-dimensional array size and T an array type like Array{S} or Array{S,N}, the data is returned as an array of this type and size.

• Without dims and if T is a vector type like Vector{S} or Memory{S}, the data is returned as a vector of type T with as many elements of type S that fit into the data.

• Without dims and if T is String, a string interpreting the data as ASCII characters is returned.

• Without dims and for any other types T, the sizeof(T) leading bytes of the data are returned as a single value of type T.

Except if T is String, trailing data bytes, if any, are ignored.

The take keyword specifies whether the returned result may steal the internal data buffer in rep[i] thus saving some memory and copy but preventing other retrieval of the data by another call to XPA.get_data. This keyword is ignored if the result cannot directly use the internal buffer. By default, take=false.

In any cases, the type of the result is predictable, so there should be no type instability issue.

See also

XPA.get, XPA.get_message, and XPA.get_server.

XPA.get_server(rep::XPA.Reply, i=1)
XPA.get_server(rep[i])
rep[i].server

yields a string identifying the server who provided the i-th answer in XPA reply rep.

See also

XPA.get, XPA.has_message, XPA.has_error, XPA.get_data and XPA.get_message.

XPA.get_message(rep::XPA.Reply, i=1)
XPA.get_message(rep[i])
rep[i].message

yields the message associated with the i-th answer in XPA reply rep. An empty string is returned if there is no message.

See also

XPA.get, XPA.has_message, XPA.has_error, XPA.get_data and XPA.get_server.

XPA.has_error(rep::XPA.Reply, i=1)
XPA.has_error(rep[i])
rep[i].has_error

yields whether i-th answer in XPA reply rep has an error whose message is given by rep[i].message.

See also

XPA.get, XPA.get_message, XPA.has_message, XPA.get_data, and XPA.get_server,

XPA.has_errors(rep::Reply) -> Bool

yields whether answer rep contains any error messages.

See also

XPA.get, XPA.has_error, and XPA.get_message.

XPA.has_message(rep::XPA.Reply, i=1)
XPA.has_message(rep[i])
rep[i].has_message

yields whether i-th answer in XPA reply rep has an associated message that is given by rep[i].message.

See also

XPA.get, XPA.get_message, XPA.has_error, XPA.get_data, and XPA.get_server,

XPA.join_arguments(args) -> str::String

joins a tuple of arguments into a single string where arguments are separated by a single space. It is implemented so as to be faster than join(args, " ") when args has less than 2 arguments. It is intended to build XPA command string from arguments.

XPA.verify(rep::Reply [, i]; throwerrors::Bool=false) -> Bool

verifies whether answer(s) in the result rep from an XPA.get or XPA.set request has no errors. If index i is specified only that specific answer is considered; otherwise, all answers are verified. If keyword throwerrors is true, an exception is thrown for the first error found if any.

XPA.set([conn,] apt, args...; data=nothing, kwds...) -> rep

sends data to one or more XPA access-points identified by apt with arguments args... (automatically converted into a single string where the arguments are separated by a single space). The result is an instance of XPA.Reply. Optional argument conn is a persistent XPA client connection (created by XPA.Client); if omitted, a per-task connection is used (see XPA.connection).

Keywords

• data specifies the data to send, may be nothing, an array, or a string.

• nmax specifies the maximum number of recipients, nmax=1 by default. Specify nmax=-1 to use the maximum possible number of XPA hosts.

• mode specifies options in the form "key1=value1,key2=value2".

• throwerrors specifies whether to check for errors. If this keyword is set true, an exception is thrown for the first error message encountered in the list of answers. By default, throwerrors is false.

• users specifies the list of possible users owning the access-point. This (temporarily) overrides the settings in environment variable XPA_NSUSERS. By default and if the environment variable XPA_NSUSERS is not set, the access-point must be owned by the caller (see Section Distinguishing Users in XPA documentation). The value is a string which may be a list of comma separated user names or "*" to access all users on a given machine.

See also

XPA.Client, XPA.get and XPA.verify.

buf = XPA.buffer(data)

yields an object buf representing the contents of data and which can be used as an argument to ccall. Argument data can be nothing, an array, or a string. If data is a dense array, buf is data. If data is another type of array, buf is data converted to an Array. If data is an ASCII string, buf is copy of data in a temporary byte buffer. If data is nothing, XPA.NullBuffer() is returned.

Standard methods like pointer or sizeof can be applied to buf to retrieve the address and the size (in bytes) of the data and Base.unsafe_convert(Ptr{Cvoid}, buf) can also be used.

See also

XPA.set.

XPA.Server

An instance of the mutable structure XPA.Server represents a server connection in the XPA Messaging System.

XPA.SendCallback <: XPA.Callback

An instance of the XPA.SendCallback structure represents a callback called to serve an XPA.get request.

XPA.store!(buf, data)
XPA.store!(buf, ptr, len)

store into the send buffer buf a dynamically allocated copy of the contents of data or of the len bytes at address ptr.

See also

XPA.Server, XPA.SendCallback, and XPA.get.

XPA.ReceiveCallback <: XPA.Callback

An instance of the XPA.ReceiveCallback structure represents a callback called to serve an XPA.set request.

XPA.peek(T, buf, i=1) -> val

yields the i-th binary value of type T stored into receive buffer buf. Bounds checking is performed unless @inbounds is active.

Another usage of the XPA.peek method is to convert the contents of the receive buffer into an array:

XPA.peek(Vector{T}, [len,] buf) -> vec
XPA.peek(Array{T[,N]}, (dim1, ..., dimN), buf) -> arr

yield a Julia vector vec or array arr whose elements are of type T and dimensions are len or (dim1, ..., dimN). For a vector, if the length is unspecified, the vector of maximal length that fits in the buffer is returned.

If keyword temporary is true, then unsafe_wrap is called (with option own=false) to wrap the buffer contents into a Julia array whose life-time cannot exceeds that of the callback. Otherwise, a copy of the buffer contents is returned.

See also

XPA.ReceiveCallback.

error(srv, msg) -> XPA.FAILURE

Communicates error message msg to the client when serving a request by XPA server srv. This method shall only be used by the send/receive callbacks of an XPA server.

See also

XPA.Server, XPA.message, XPA.SendCallback, and XPA.ReceiveCallback.

XPA.poll(sec, maxreq)

polls for XPA events. This method is meant to implement a polling event loop which checks for and processes XPA requests without blocking.

Argument sec specifies a timeout in seconds (rounded to millisecond precision). If sec is positive, the method blocks no longer than this amount of time. If sec is strictly negative, the routine blocks until the occurrence of an event to be processed.

Argument maxreq specifies how many requests will be processed. If maxreq < 0, then no events are processed, but instead, the returned value indicates the number of events that are pending. If maxreq == 0, then all currently pending requests will be processed. Otherwise, up to maxreq requests will be processed. The most usual values for maxreq are 0 to process all requests and 1 to process one request.

The following example implements a polling loop which has no noticeable impact on the consumption of CPU when no requests are emitted to the server:

const __running = Ref{Bool}(false)

function run()
    global __running
    __running[] = true
    while __running[]
        XPA.poll(-1, 1)
    end
end

Here the global variable __running is a reference to a boolean whose value indicates whether to continue to run the XPA server(s) created by the process. The idea is to pass the reference to the callbacks of the server (as their client data for instance) and let the callbacks stop the loop by setting the contents of the reference to false.

Another possibility is to use XPA.mainloop (which to see).

To let Julia performs other tasks, the polling method may be repeatedly called by a Julia timer. The following example does this. Calling resume starts polling for XPA events immediately and then every 100ms. Calling suspend suspends the processing of XPA events.

const __timer = Ref{Timer}()

ispolling() = (isdefined(__timer, 1) && isopen(__timer[]))

resume() =
    if ! ispolling()
        __timer[] = Timer((tm) -> XPA.poll(0, 0), 0.0, interval=0.1)
    end

suspend() =
    ispolling() && close(__timer[])

See also

XPA.Server and XPA.mainloop.

XPA.message(srv, msg)

sets a specific acknowledgment message back to the client. Argument srv is the XPA server serving the client and msg is the acknowledgment message. This method shall only be used by the receive callback of an XPA server.

See also

XPA.Server, XPA.error, and XPA.ReceiveCallback.

XPA.mainloop()

runs XPA event loop which handles the requests sent to the server(s) created by this process. The loop runs until all servers created by this process have been closed.

In the following example, the receive callback function close the server when it receives a "quit" command:

function rproc(::Nothing, srv::XPA.Server, params::String,
               buf::Ptr{UInt8}, len::Integer)
    status = XPA.SUCCESS
    if params == "quit"
        close(srv)
    elseif params == ...
        ...
    end
    return status
end

See also

XPA.Server and XPA.mainloop.

XPA.address(apt) -> addr

yields the address of XPA access-point apt which can be: an instance of XPA.AccessPoint, a string with a valid XPA server address or a server class:name identifier. In the latter case, XPA.find is called to find a matching server which is much longer.

XPA.list(f = Returns(true); kwds...)

yields a list of available XPA access-points. The result is a vector of XPA.AccessPoint instances. Optional argument f is a predicate function to filter which access-points to keep.

For example, to only keep the access-points owned by the user:

apts = XPA.list() do apt
    apt.user == ENV["USER"]
end

Keywords

• method is nothing (the default) or one of inet, unix (or local), or localhost as a symbol or a string to require a specific connection method.

• on_error is a symbol indicating what to do in case of unexpected reply by the XPA name server; it can be :throw to throw an exception, :warn (the default) to print a warning, anything else to silently ignore the error.

• xpaget is to specify the method to contact the XPA name server; it can be a string with the path to the xpaget executable or a function behaving like XPA.get. Using XPA.get has fewer possibilities so, by default, the xpaget executable provided by XPA_jll artifact is used.

See also

XPA.find to select a single access-point.

XPA.AccessPoint for the properties of access-points that can be used in the predicate function f.

apt = XPA.AccessPoint(str)
apt = XPA.AccessPoint(class, name, address, user, access)
apt = XPA.AccessPoint(; class="", name="", address="", user="", access=0)

builds a structure representing an XPA server for a client. If single argument is a string str, it is parsed assuming the same format as the output of xpans. Otherwise the arguments/keywords reflect the properties of the object:

apt.class   # access-point class
apt.name    # access-point name
apt.address # server address (host:port for inet socket, path for unix socket)
apt.user    # access-point owner
apt.access  # allowed access

At least the address shall be provided.

All properties are strings except access which is an unsigned integer whose bits are set as follows:

 !iszero(apt.access & 1) # holds if `set` command allowed
 !iszero(apt.access & 2) # holds if `get` command allowed
 !iszero(apt.access & 4) # holds if `info` command allowed

The constructors also accept access as a string composed of characters 'g', 's', and 'i' respectively indicating whether get, set, and info commands are implemented by the server.

Method isopen(apt) yields whether address is not an empty string.

See also

XPA.list to retrieve a vector of existing XPA servers possibly filtered by some provided function.

XPA.find to obtain the access-point of a single XPA server.

XPA.find(f = Returns(true); kwds...)

yields the access-point of the XPA server matching the requirements implemented by the predicate function f and keywords kwds.... In principle, the result is either a single instance of XPA.AccessPoint or nothing if no matching server is found (this type assertion may only be invalidated by the function specified via the select keyword).

Keywords

In addition to the keywords accepted by XPA.list, the following keyword(s) are available:

• select specifies a strategy to apply if more than one access-point is found. select can be a function (like first or last to keep the first or last entry), the symbolic name :interact to ask the user to make the selection via a REPL menu, or anything else to throw an exception. The default is :throw. If select is a function, it is called with a vector of 2 or more matching instances of XPA.AccessPoint and the result of select is returned by XPA.find.

• throwerrors specifies whether to throw an error if no matching servers are found instead of returning nothing.

Example

apt = XPA.find(; interact = isinteractive(), method = :local)

See also

XPA.list which is called to retrieve a list of access-points with the predicate function f.

XPA.AccessPoint for the properties of access-points that can be used in the predicate function f.

XPA.getconfig(key) -> val

yields the value associated with configuration parameter key (a string or a symbol). The following parameters are available (see XPA doc. for more information):

Also see XPA.setconfig!.

XPA.setconfig!(key, val) -> oldval

set the value associated with configuration parameter key to be val. The previous value is returned.

Also see XPA.getconfig.

s = XPA.preserve_state(dict, key[, val])

Yield an object that can be used to restore the state of dictionary dict for entry key with XPA.restore_state. For improved type-stability, optional argument val may be specified with a substitute value of the same type as those stored in dict if key is not in dict.

The call:

XPA.preserve_state(f::Function, dict, key[, val])

is equivalent to:

let s = XPA.preserve_state(dict, key[, val])
    try
        f()
    finally
        XPA.restore_state(s)
    end
end

which is suitable for the do-block syntax.

XPA.restore_state(s)

Restore the state saved in s by XPA.preserve_state.

XPA.SUCCESS and XPA.FAILURE are the possible values returned by the callbacks of an XPA server.

XPA.SUCCESS and XPA.FAILURE are the possible values returned by the callbacks of an XPA server.