Changeset 38237 in project


Ignore:
Timestamp:
03/13/20 05:00:05 (3 weeks ago)
Author:
alicemaz
Message:

replace nanomsg wiki page with current readme (generated from markdown-svnwiki)

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/5/nanomsg

    r36840 r38237  
    1111Nanomsg is smaller, written in C, has a simplified API (sockets are
    1212simple ints), no multipart messages, and has explicit support for poll
    13 on a socket's recv file-descriptor.
     13on a socket's recv file-descriptor, which integrates well with
     14[[http://call-cc.org/|Chicken Scheme]].
    1415
    1516
    1617=== Requirements
    17 This egg requires nanomsg-1.0 or (probably) above.
     18This egg requires
     19[[https://github.com/nanomsg/nanomsg/releases/tag/1.0.0|nanomsg-1.0.0]]
     20or higher.
     21
    1822
    1923=== Repository
    20 
    21 [[https://github.com/Adellica/chicken-nanomsg|https://github.com/Adellica/chicken-nanomsg]]
    22 
     24[[https://github.com/Adellica/chicken-nanomsg]]
    2325
    2426=== API
    25 <procedure> (nn-socket protocol [domain])</procedure>
     27<procedure>(nn-socket protocol [domain])</procedure>
    2628
    27 Create a nanomsg socket. Protocol can be any of the symbols pair, pub,
    28 sub, pull, push, req, rep, surveyor, respondent or bus. Domain can be
    29 the symbol sp or raw, and defaults to sp.
     29[[http://nanomsg.org/v1.0.0/nn_socket.3.html|Create]] a nanomsg
     30socket. Protocol can be any of the symbols {{pair}}, {{pub}}, {{sub}},
     31{{pull}}, {{push}}, {{req}}, {{rep}}, {{surveyor}}, {{respondent}} or
     32{{bus}}. Domain can be the symbol {{sp}} or {{sp-raw}}, and defaults to
     33{{sp}}. The returned socket is automatically closed with {{nn-close}} when
     34it is garbage-collected.
    3035
    31 <procedure> (nn-bind socket address)</procedure>
     36<procedure>(nn-socket* protocol [domain])</procedure>
    3237
    33 [[http://nanomsg.org/v0.6/nn_bind.3.html|Binds]] nanomsg socket to
     38Just like {{nn-socket}}, but does '''not''' attach a finalizer on the
     39returned socket object. You must manually call {{nn-close}} on the
     40socket after use.
     41
     42<procedure>(nn-bind socket address)</procedure>
     43
     44[[http://nanomsg.org/v1.0.0/nn_bind.3.html|Binds]] nanomsg socket to
    3445address, where address is a string of the form
    35 "ipc:///var/ipc/music.nn.pair" or "tcp://0.0.0.0:10080". If the
     46{{"ipc:///var/ipc/music.nn.pair"}} or {{"tcp://0.0.0.0:10080"}}. If the
    3647nn-library can't parse the address string, it throws an "Illegal
    3748argument" error.
    3849
    39 <procedure> (nn-connect socket address)</procedure>
     50<procedure>(nn-connect socket address)</procedure>
    4051
    41 [[http://nanomsg.org/v0.6/nn_connect.3.html|Connects]] nanomsg socket
     52[[http://nanomsg.org/v1.0.0/nn_connect.3.html|Connects]] nanomsg socket
    4253{{socket}} to {{address}}.
    4354
    44 <procedure> (nn-subscribe socket prefix)</procedure>
     55<procedure>(nn-subscribe socket prefix)</procedure>
    4556
    46 Set the [[http://nanomsg.org/v0.6/nn_pubsub.7.html|NN_SUBSCRIBE]]
     57Set the [[http://nanomsg.org/v1.0.0/nn_pubsub.7.html|NN_SUB_SUBSCRIBE]]
    4758option on {{socket}} which will make the socket receive to all messages
    48 that start with {{prefix}}. Note that if this is never called, {{(nn-sock
    49 'sub)}} sockets will never receive anything.
     59that start with {{prefix}}.
    5060
    51 <procedure> (nn-recv socket)</procedure>
     61Note that if this is never called, {{(nn-sock 'sub)}} sockets will
     62never receive anything.
     63
     64<procedure>(nn-send socket msg)</procedure>
     65
     66Send a message on {{socket}}, using the socket's semantics. {{msg}} must
     67be a string. This will not block other srfi-18 threads. Returns the
     68number of bytes sent.
     69
     70<procedure>(nn-send* socket msg flags)</procedure>
     71
     72Like {{nn-send}}, but may block other srfi-18 threads when {{flags}} is
     73{{0}}. {{flags}} may be {{nn/dontwait}} in which case {{nn-send*}} always
     74returns immediately, and returns {{#f}} is the operation would block
     75(number of bytes otherwise).
     76
     77<procedure>(nn-recv socket)</procedure>
    5278
    5379Receive a message from socket. This blocks until a message is received
     
    5682state.
    5783
    58 <procedure> (nn-send socket msg)</procedure>
     84Note that memory is copied from the nanomsg buffer into a new scheme
     85string.
    5986
    60 Send a message on {{socket}}, using the socket's semantics. {{msg}} must
    61 be a string.
    62 
    63 In the current implementation, this operation may block for certain
    64 protocols in which case other srfi-18 threads block too.
    65 
    66 <procedure> (nn-recv* socket flags)</procedure>
     87<procedure>(nn-recv* socket flags)</procedure>
    6788
    6889Receive a message from socket. This will block other srfi-18 threads,
    6990unless the {{nn/dontwait}} flag is specified, in which case {{nn-recv*}}
    70 will immediately with either a message as a string or #f (for
    71 EAGAIN). An error is thrown if {{socket}} is in an illegal state.
     91will exit immediately with either a message as a string or #f (for
     92{{EAGAIN}}). An error is thrown if {{socket}} is in an illegal state.
    7293
    73 Note that memory is copied from the nanomsg buffer into a new scheme
    74 string.
     94Note that this can be combined with {{(nn-socket-rcvfd socket)}} for
     95custom polling.
    7596
    76 <procedure> (nn-recv! socket buffer size flags)</procedure>
    77 
    78 A version of {{nn-recv*}} which requires a preallocated buffer. If the
    79 size of the buffer can be found automatically (using
    80 {{number-of-bytes}}), size can be {{#f}}.
    81 
    82 <procedure> (nn-close socket)</procedure>
     97<procedure>(nn-close socket)</procedure>
    8398
    8499Explicitly close {{socket}}. This is normally not needed as this is done
    85100in the socket's finalizer.
    86101
     102<procedure>(nn-shutdown socket endpoint)</procedure>
     103
     104Removed {{endpoint}} from {{socket}}.
     105See [[http://nanomsg.org/v1.0.0/nn_shutdown.3.html|nn_shutdown]].
     106
     107<procedure>(nn-get-statistic socket statistic)</procedure>
     108
     109Retrieve a statistic from {{socket}}. {{statistic}} may be any one of
     110these symbols: {{established-connections}} {{accepted-connections}}
     111{{dropped-connections}} {{broken-connections}} {{connect-errors}}
     112{{bind-errors}} {{accept-errors}} {{current-connections}}
     113{{inprogress-connections}} {{current-ep-errors}} {{messages-sent}}
     114{{messages-received}} {{bytes-sent}} {{bytes-received}}
     115{{current-snd-priority}}. See
     116[[http://nanomsg.org/v1.0.0/nn_get_statistic.3.html|nn_get_statistic]].
     117
     118<procedure>(nn-socket-name socket)</procedure>
     119<procedure>(nn-socket-linger socket)</procedure>
     120<procedure>(nn-socket-rcvtimeo socket)</procedure>
     121<procedure>(nn-socket-sndtimeo socket)</procedure>
     122<procedure>(nn-socket-rcvbuf socket)</procedure>
     123<procedure>(nn-socket-sndbuf socket)</procedure>
     124<procedure>(nn-socket-sndfd socket)</procedure>
     125<procedure>(nn-socket-rcvfd socket)</procedure>
     126<procedure>(nn-socket-protocol socket)</procedure>
     127<procedure>(nn-socket-domain socket)</procedure>
     128<procedure>(nn-socket-maxttl socket)</procedure>
     129<procedure>(nn-socket-rcvmaxsize socket)</procedure>
     130<procedure>(nn-socket-rcvprio socket)</procedure>
     131<procedure>(nn-socket-sndprio socket)</procedure>
     132<procedure>(nn-socket-reconnect-ivl-max socket)</procedure>
     133<procedure>(nn-socket-reconnect-ivl socket)</procedure>
     134<procedure>(nn-socket-ipv4only socket)</procedure>
     135<procedure>(nn-req-socket-resend-ivl socket)</procedure>
     136
     137Retrieve the socket option associated with {{socket}}. Most of these
     138also provide setters so that you can, for example, can do {{(set!
     139(nn-socket-name s) "foo")}}.
     140
     141For other socket options, try {{nn-getsockopt/string}},
     142{{nn-getsockopt/int}}, {{nn-setsockopt/string}} and {{nn-setsockopt/int}}.
     143
    87144
    88145=== Development Status
    89 These bindings are incomplete, but all protocols and transport types
    90 should be supported. However, socket options ({{nn_setsockopt}} and
    91 {{nn_getsockopt}}) aren't supported with the exception of
    92 {{nn-subscribe}}. Patches are welcome!
    93 
    94 Favored TODO's:
    95 - support socket options
    96 - bundle nanomsg itself?
     146These bindings to nanomsg 1.0.0 should be fairly complete, the only
     147missing functionality is the control messages ({{nn_recvmsg}},
     148{{nn_sendmsg}} and {{nn_cmsg}}). Also, note that the egg hasn't undergode
     149rigerous testing in the field yet.
    97150
    98151
    99152=== Sample
    100 <enscript highlight="scheme">    
     153<enscript highlight="scheme">
    101154;; test.scm
    102 (use nanomsg)
     155(import nanomsg)
    103156
    104157(define s (nn-socket 'rep))
     
    114167then test with the brilliant {{nanocat}} util that comes with [nanomsg]:
    115168
    116 <enscript highlight="bash">    
     169<enscript highlight="bash">
    117170$ csi -s test.scm &
    118171$ nanocat --req -l22022 -D"bottles of beer:" -A --interval 1
    119172</enscript>
    120 
Note: See TracChangeset for help on using the changeset viewer.