Changeset 31613 in project

10/07/14 02:48:14 (5 years ago)

Anonymous wiki edit for IP []: Finish high level api.

1 edited


  • wiki/eggref/4/websockets

    r31612 r31613  
    101101The maximum message size supported by {{websockets}} is {{1GiB}}.
    103 ==== High level interface
     103=== High level interface
    105105As noted in the description, the high level interface is not a "traditional" asynchronous API as is often seen with other websocket libraries. Instead a blocking and synchronous interface is provided as well as an asynchronous ''backed'' interface that looks and behaves like a blocking interface. See the function definitions below for further details.
    109109The main difference between {{with-websocket}} and {{with-concurrent-websocket}} is that messages are guaranteed to be delivered in order with {{with-websocket}}. This also means that no messages will be read into memory and processed unless a call is made to {{receive-message}}. This includes pong messages that may be sent in response to any pings sent in the background ping thread, if enabled. See the definition of {{ping-interval}} for more details on how background pings and pongs work.
    111 ===== {{with-websocket}}
     111==== {{with-websocket}}
    112112<procedure>(with-websocket [procedure])</procedure>
    118118Unless you expect a high volume of messages or messages of very large size on one websocket connection then this is the recommended procedure to use. It is easier to program when you know messages will arrive in order and it is more lightweight.
    120 ===== {{with-concurrent-websocket}}
     120==== {{with-concurrent-websocket}}
    121121<procedure>(with-concurrent-websocket [procedure])</procedure>
    127127Sending messages are still done in a blocking fashion but sending is relatively fast and will likely not be a problem. This could change in the future though so don't rely on it.
    129 ===== {{receive-message}}
     129==== {{receive-message}}
    130130<procedure>(receive-message #!optional (ws (current-websocket)))</procedure>
     132Read in a message from the client. Returns two values. The first is the message and the second is the message type, either {{'text}} or {{'binary}}. Regardless of the message type the message itself will always be a string. Takes an optional {{websocket}} object that is bound to {{(current-websocket)}} by default. It will always block until a message is received but if used within {{with-concurrent-websocket}} it will not block other messages from being received or processed.
     134It is thread safe.
     136==== {{send-message}}
     137<procedure>(send-message message-type #!optional (data "") (ws (current-websocket)))</procedure>
     139Send a message to the client. {{message-type}} is one of the types listed under the {{message-types}} section. Usually this will be {{'text}} or {{'binary}} but any valid type is allowed. {{data}} is optional and defaults to an empty message. It can be a string or a u8vector that will be sent to the client. Note that currently u8vectors must be copied before being sent due to some CHICKEN internal limitations, strings will not. {{send-message}} also takes an optional {{websocket}} object that is bound to {{(current-websocket)}} by default.
     141It is thread safe.
Note: See TracChangeset for help on using the changeset viewer.