vortex — LuaVortex base module: base functions (create listeners, register profiles)

This modules includes all functions required to establish a BEEP session, create channels and develop BEEP profiles.

This module also includes type definition for the following classes:

Module API

vortex.create_listener(ctx, host, port)

Allows to create a BEEP listener to receiving incoming connections. Here is an example:

# create a listener
listener = vortex.create_listener (ctx, "0.0.0.0", "44010")

# check listener started
if not listener.is_ok ():
    # do some error handling
    sys.exit (-1)

# do a wait operation
vortex.wait_listeners (ctx, true)
Parameters:
  • ctx (vortex.Ctx) – vortex context where the listener will be created
  • host (String) – the hostname
  • port (String) – the port to connect to
Return type:

vortex.Connection representing the listener created.

vortex.wait_listeners(ctx[, unlock_on_signal])

Allows to perform a wait operation until vortex context is finished or due to a signal received (when unlock_on_signal is set to true).

Note this call is not necessary in the case your application or host program has a wait to ensure the program do not finish. This method, like C function vortex_listener_wait, is just one method to ensure the calling thread (usually the main()) do not ends until we wait for requests.

This function is often use at the server side. To unlock manually call to vortex.unlock_listeners

Parameters:
  • ctx (vortex.Ctx) – context where a listener or a set of listener were created.
  • unlock_on_signal (Integer: true or false) – unlock_on_signal expects to receive true to make wait_listener to unlock on signal received.
vortex.unlock_listeners(ctx)

Unlocks the vortex.wait_listeners caller (if any).

Parameters:ctx (vortex.Ctx) – context where a listener or a set of listener were created.
vortex.register_profile(ctx = vortex.Ctx, uri, frame_received[, frame_received_data][, start][, start_data][, close][, close_data])

Allows to register a supported profile so the current BEEP, inside the provided vortex.Ctx will accept incoming requests to open a channel running such profile.

The function requires to mandatory parameters (ctx and uri). The rest of parameters are handlers used to handle different situations (start channel request, close channel request, and frame received).

A usual register operation will look like this:

vortex.register_profile (ctx, your_uri, frame_received_handler)

Where frame_received_handler will look like:

function frame_received_handler (conn, channel, frame, data)
    -- frame recevied, look into frame.payload
    return
end

In the case you want to provide a start handler, you need to also define the frame received handler. Here is how to setup start handler:

vortex.register_profile (ctx, your_profile,
                  -- frame received
                  frame_received_handler, nil,
                  -- start handler
                  start_handler, nil)
Parameters:
  • ctx (vortex.Ctx) – context where the profile will be registered
  • uri (string) – Profile unique string identification
  • start (Channel start handler) – User defined handler that will be used to manage incoming start channel requests. The handler must provide return true to accept the channel to be created or false to deny it.
  • start_data (object) – User defined data that will notified along with corresponding data at start handler.
  • close (Channel close handler) – User defined handler that will be used to manage incoming close channel requests. The handler must provide return true to accept the channel to be closed or false to deny it.
  • close_data (object) – User defined data that will notified along with corresponding data at close channel handler.
  • frame_received (Frame received handler) – User defined handler that will be used to manage frames received under channels running this profile.
  • frame_received_data (object) – User defined data that will notified along with corresponding data at frame received handler.
vortex.yield([timeout])

Because lua has no GIL (global interpreter lock) concept like python, the executing thread must yield the execution to let other threads to enter into the lua space. In python this is done automatically. In lua, the user must take care of this detail, especially for client side code (for server side programming, this is mostly not required).

You can yield forever until other thread enters into lua space or just yield during a limited period (timeout is measured in microseconds: 1 second = 1000000 microseconds).

Nothing happens if you call to yield several times a now event or thread is attended.

Here is an example:

-- send message
if channel:send_msg ("This is a test...", 17) == nil then
   print ("ERROR: expected to find proper send operation..")
   return false
end

-- now yield
print ("Let other threads to enter..")
vortex.yield (1000000)

-- if we are here, we own the execution

See also vortex.wait_events and vortex.event_fd to know more about methods that provides a notification about when it is required to yield.

Parameters:timeout (Number) – Optional timeout that control how long to wait
vortex.event_fd()

This function allows to get a file descriptor that can be checked for changes that indicates a call to vortex.yield is required (another thread is asking to acquire permission to execute). This descriptor can be used integrated into a polling method (like select() or similar). In the case changes are detected, the running thread must call to vortex.yield to yield execution.

Return type:File descriptor to watch for changes. Do not read or close descriptor returned.
vortex.wait_events([timeout])

Implements a select () operation over the internal descriptor (that can be acquired by calling to vortex.event_fd), unlocking the caller when a change is detected. In such case, a call to vortex.yield is required to yield execution.

This function exists mainly to provide a simple method to implement a “wait for events” method especially because socket.select method provided by lua socket module only accepts descriptors created by the socket module.

A typical usage example is:

-- wait for events
while vortex.wait_events () do
     print ("Event detected, yielding execution....")
     vortex.yield ()
end

NOTE: if you are integrating LuaVortex with another product like a gui or similar, this method is not recommended. Try to see if that toolkit can watch for changes on a particular descriptor, and put under supervision the descriptor returned by vortex.event_fd. Then you call to vortex.yield, every time a change is detected on that descriptor.

Parameters:timeout (Number) – Optional timeout that control how long to wait