# -*- coding: utf-8 -*-
"""
The `supcon` Framework provides inter-process communication (IPC) and remote
procedure call (RPC) mechanisms, that allow communication between multiple
computer programs running on different hosts in a TCP/IP network.

Each participating program exposes one or more `supcon.intf.Node`s to the
network. Each `supcon.intf.Node` has a name that must be unique among the
nodes of the communicating programs.

    #!python
    import supcon.core
    
    lServer = supcon.core.Node('my-unique-server')
    lClient = supcon.core.Node('my-unique-client')

You can give a `supcon.intf.Node` one or more endpoints on the network to either
connect to or to listen for incomming connections.

    #!python
    from twisted.internet import reactor
    from twisted.internet.endpoints import TCP4ClientEndpoint
    from twisted.internet.endpoints import TCP4ServerEndpoint

    lServer.listen(TCP4ServerEndpoint(reactor, 7000))
    lClient.connect(TCP4ClientEndpoint(reactor, 'localhost', 7000))

When a `supcon.intf.Node` is unable to create a connection to the given endpoint
or an established connection terminates, the node tries to reestablish the
connection.

Programs can expose events and provide methods via the node. These events and
methods are defined in `supcon.intf.Interface`s. Lets create one:

    #!python
    import supcon.intf

    timerIntf = supcon.intf.Interface({
      'name': 'com.example.Timer',
      'events': [
        {
          'name': 'timeout',
          'args': [
            { 'name': 'timer', 'description': '(str) - The name of the timer' }
          ]
          'description': 'Gets triggerd, whenever a timer times out.'
        }
      ],
      'methods': [
        {
          'name': 'add',
          'inArgs': [
            { 'name': 'timer', 'description': '(str) - A name for the timer' }
            { 'name': 'seconds', 'description': '(float) - A duration' }
          ],
          'description': 'Adds a new timer.'
        }
      ]
    })

Lets implement the interface and register the implementation at the local node:

    #!python

    timerImpl = supcon.intf.Implementation(timerIntf)
    
    def fireTimeout(timer):
      timerImpl.fire('timeout', { 'timer': timer })
    
    def onAdd(timer, seconds):
      reactor.callLater(seconds, lambda: fireTimeout(timer))

    timerImpl.setCallCb('add', onAdd)

    lServer.register('/myTimer', timerImpl)

Now you can watch for timeout events and add a timer via the
<code>lClient</code> reference:

    #!python
    lClient.on('my-unique-server', '/myTimer', 'com.example.Timer', 'timeout', 
      lambda *args: print(', '.join([ '{}'.format(i) for i in args ]))
    )

    lClient.call('my-unique-server', '/myTimer', 'com.example.Timer', 'add', {
      'timer': '5Seconds', 'seconds': 5
    })

And don't forget to start the reactor (aka event loop)

    #!python
    reactor.run()

"""