Reference

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 thread (a different connection is memorized for each Julia thread).

Per-thread client connections are automatically open (or even re-open) as needed.

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

retrieves data from one or more XPA access points identified by apt (a template name, a host:port string or the name of a Unix socket file) with arguments args... (automatically converted into a single string where the arguments are separated by a single space). Optional argument conn is a persistent XPA client connection (created by XPA.Client); if omitted, a per-thread 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). The following keywords are available:

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

• 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. By default, throwerrors is false.

• 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 wich may be a list of comma separated user names or "*" to access all users on a given machine.

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 list of dimensions:

• If only T is specified, it can be String to return a string interpreting the data as ASCII characters or a type like Vector{S} to return the largest vector of elements of type S that can be extracted from the returned data.

• If both T and dims are specified, T can be a type like Array{S} or Array{S,N} and dims a list of N dimensions to retrieve the data as an array of type Array{S,N}.

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

XPA.Reply is used to store the answer(s) of XPA.get and XPA.set requests. Method length applied to an object of type Reply yields the number of replies. Methods XPA.get_data, XPA.get_server and XPA.get_message can be used to retrieve the contents of an object of type XPA.Reply.

XPA.get_data([T, [dims,]] rep, i=1; preserve=false)

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

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

• If only T is specified, it can be String to return a string interpreting the data as ASCII characters or a type like Vector{S} to return the largest vector of elements of type S that can be extracted from the data.

• If both T and dims are specified, T can be an array type like Array{S} or Array{S,N} and dims a list of N dimensions to retrieve the data as an array of type Array{S,N}.

Keyword preserve can be used to specifiy whether or not to preserve the internal data buffer in rep for another call to XPA.get_data. By default, preserve=true when T = String is specified and preserve=false otherwise.

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

See also XPA.get, XPA.get_message, XPA.get_server.

XPA.get_server(rep, i=1)

yields the XPA identifier of the server which sent the i-th reply in XPA answer rep. An empty string is returned if there is no i-th reply.

See also XPA.get, XPA.get_message.

XPA.get_message(rep, i=1)

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

See also XPA.get, XPA.has_message, XPA.has_error, XPA.get_server.

XPA.has_error(rep, i=1) -> boolean

yields whether i-th XPA answer rep contains an error message. The error message can be retrieved by calling XPA.get_message(rep, i).

See also XPA.get, XPA.has_message, XPA.get_message.

XPA.has_errors(rep) -> boolean

yields whether answer rep contains any error messages.

See also XPA.get, XPA.has_error, XPA.get_message.

XPA.has_message(rep, i=1) -> boolean

yields whether i-th XPA answer rep contains an error message.

See also XPA.get, XPA.has_message.

XPA.join_arguments(args)

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 [, i]; throwerrors::Bool=false) -> boolean

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-thread connection is used (see XPA.connection).

The following keywords are available:

• Keyword data specifies the data to send, may be nothing, an array or a string. If it is an array, it must have contiguous elements (as a for a dense array) and must implement the pointer method.

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

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

• 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. By default, throwerrors is false.

• 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 wich 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 without the risk of having the data garbage collected. Argument data can be nothing, a dense array or a string. If data is an array buf is just an alias for data. If data is a string, buf is a temporary byte buffer where the string has been copied.

Standard methods pointer and sizeof can be applied to buf to retieve the address and the size (in bytes) of the data and convert(Ptr{Cvoid},buf) can also be used.

See also XPA.set.

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

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

XPA.store!(buf, data)

or

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.

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.

Also see: XPA.Server, XPA.message, XPA.SendCallback, 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 occurence 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[])

Also see: XPA.Server, 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.

Also see: XPA.Server, XPA.error, 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

Also see: XPA.Server, XPA.mainloop.

XPA.address(apt) -> addr

yields the address of XPA accesspoint 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(conn=XPA.connection())

yields a list of available XPA access points. The result is a vector of XPA.AccessPoint instances. Optional argument conn is a persistent XPA client connection (created by XPA.Client); if omitted, a per-thread connection is used (see XPA.connection).

See also XPA.Client, XPA.connection and XPA.find.

An instance of the XPA.AccessPoint structure represents an available XPA server. A vector of such instances is returned by the XPA.list utility.

XPA.find([conn=XPA.connection(),] ident) -> apt

yields the accesspoint of the first XPA server matching ident or nothing if none is found. If a match is found, the result apt is an instance of XPA.AccessPoint and has the following members:

apt.class   # class of the access point (String)
apt.name    # name of the access point
apt.addr    # socket access method (host:port for inet,
apt.user    # user name of access point owner
apt.access  # allowed access

all members are Strings but the last one, access, which is an UInt.

Argument ident may be a regular expression or a string of the form CLASS:NAME where CLASS and CLASS are matched against the server class and name respectively (they may be "*" to match any).

Optional argument conn is a persistent XPA client connection (created by XPA.Client); if omitted, a per-thread connection is used (see XPA.connection).

Keyword user may be used to specify the user name of the owner of the server process, for instance ENV["user"] to match your servers. The default is user="*" which matches any user.

Keyword throwerrors may be set true (it is false by default) to automatically throw an exception if no match is found (instead of returning nothing).

See also XPA.Client, XPA.address and XPA.list.

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.

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