|
| 1 | +# Usage |
| 2 | + |
| 3 | + |
| 4 | +## Basic library usage |
| 5 | +*** |
| 6 | + |
| 7 | +The API is in late alpha testing, and has not yet reached a beta (pre-release) stage. |
| 8 | + |
| 9 | +Here is an example of usage (circa v1.4) |
| 10 | + |
| 11 | +```python3 |
| 12 | +import multicast as multicast |
| 13 | +from multiprocessing import Process as Process |
| 14 | + |
| 15 | +# setup some stuff |
| 16 | +_fixture_PORT_arg = int(59595) |
| 17 | +_fixture_mcast_GRP_arg = """224.0.0.1""" # only use dotted notation for multicast group addresses |
| 18 | +_fixture_host_BIND_arg |
| 19 | +_fixture_HEAR_args = [ |
| 20 | + """--port""", _fixture_PORT_arg, |
| 21 | + """--join-mcast-groups""", _fixture_mcast_GRP_arg, |
| 22 | + """--bind-group""", _fixture_mcast_GRP_arg" |
| 23 | +] |
| 24 | + |
| 25 | +# spwan a listening proc |
| 26 | + |
| 27 | +def inputHandle() |
| 28 | + buffer_string = str("""""") |
| 29 | + buffer_string += multicast.recv.hearstep([_fixture_mcast_GRP_arg], _fixture_PORT_arg, _fixture_host_BIND_arg, _fixture_mcast_GRP_arg) |
| 30 | + return buffer_string |
| 31 | + |
| 32 | +def printLoopStub(func): |
| 33 | + for i in range( 0, 5 ): |
| 34 | + print( str( func() ) ) |
| 35 | + |
| 36 | +p = Process( |
| 37 | + target=multicast.__main__.McastDispatch().doStep, |
| 38 | + name="HEAR", args=("HEAR", _fixture_HEAR_args,) |
| 39 | + ) |
| 40 | +p.start() |
| 41 | + |
| 42 | +# ... probably will return with nothing outside a handler function in a loop |
| 43 | +``` |
| 44 | +and elsewhere (like another function or even module) for the sender: |
| 45 | +```python3 |
| 46 | + |
| 47 | +# assuming already did 'import multicast as multicast' |
| 48 | + |
| 49 | +_fixture_SAY_args = [ |
| 50 | + """--port""", _fixture_PORT_arg, |
| 51 | + """--mcast-group""", _fixture_mcast_GRP_arg, |
| 52 | + """--message""", """'test message'""" |
| 53 | +] |
| 54 | +try: |
| 55 | + multicast.__main__.McastDispatch().doStep("SAY", _fixture_SAY_args) |
| 56 | + # Hint: use a loop to repeat or different arguments to varry message. |
| 57 | +except Exception: |
| 58 | + p.join() |
| 59 | + raise RuntimeException("multicast seems to have failed, blah, blah") |
| 60 | + |
| 61 | +# clean up some stuff |
| 62 | +p.join() # if not already handled don't forget to join the process and other overhead |
| 63 | +didWork = (int(p.exitcode) <= int(0)) # if you use a loop and need to know the exit code |
| 64 | + |
| 65 | +``` |
| 66 | +#### Caveat: the above examples assume the reader is knowledgeable about general `IPC` theory and the standard python `multiprocessing` module and its use. |
| 67 | + |
| 68 | + |
| 69 | + |
| 70 | +## CLI Usage |
| 71 | +*** |
| 72 | + |
| 73 | +The CLI is actually not the best way to use this kind of library so it should not be considered the full implementation. For testing/prototyping though it is quite convenient, thus I begin with it. |
| 74 | + |
| 75 | +CLI should work like so: |
| 76 | + |
| 77 | +```plain |
| 78 | +multicast (SAY|RECV|HEAR) [-h|--help] [--use-std] [--daemon] [--port PORT] [--iface IFACE] [--pipe|-m MESSAGE|--message MESSAGE] [--group BIND_GROUP] [--groups [JOIN_MCAST_GROUPS ...]] |
| 79 | +``` |
| 80 | + |
| 81 | +The commands are `SAY`, `RECV`, and `HEAR` for the CLI and are analogus to `send` listen/accept and echo functions of a 1-to-1 connection. |
| 82 | + |
| 83 | +### `SAY` |
| 84 | + |
| 85 | +The `SAY` command is used to send data messages via multicast datagrams. |
| 86 | +* Note: the `--daemon` flag has no effect on the `SAY` command. |
| 87 | + |
| 88 | +### `RECV` |
| 89 | + |
| 90 | +The `RECV` command is used to receive multicast datagrams by listening or "joining" a multicast group. |
| 91 | +* If the `--use-std` flag is set the output is printed to the standard-output |
| 92 | +* This command is purely for testing or interfacing with external components and not intended as a first-class API |
| 93 | +* Note: If the `--daemon` flag is used the process will loop after reporting each datagrams until canceled, it has no effect on the `RECV` command. |
| 94 | + |
| 95 | +### `HEAR` |
| 96 | + |
| 97 | +The `HEAR` command is used to send data acknowledged messages via "HEAR" messages echoing select received multicast datagrams. |
| 98 | +* While mostly a testing function it is possible to use `HEAR` as a proxy for other send/recv instances by using the `--daemon` flag |
| 99 | +* Note: this will use the same port for sends and receives and can lead to data loss if less than two groups are used. |
| 100 | +* If more than one group is used via the `--groups` flag then all but the bind group (via `--group`) will be echoed to the bind group. |
0 commit comments