Connel Outline
Lawrence J. Dickson
LAZM.org
6 August 2013


SUMMARY

This note outlines the Connel code, as placed in Apache 2.0 open source,
as of 5 August 2013. This will be released to early-release backers upon
Kickstarter project success. This includes the main Connel library, some
auxiliary libraries, and several functional development, test and spy
programs running in Linux and Windows. It also includes partial
documentation and a pseudocode example. All the library code has been
exercised thoroughly by a proprietary robotics development (not
included).


CONTENTS OF DIRECTORY AS OF 5 AUGUST 2013

Here is the description of what is currently found in the directory:

 Connel main library
 2 auxiliary Connel libraries
 1 non-Connel library
 13 programs using Connel
 8 non-Connel programs (mostly lead-ups)
 Linux and Windows makefiles
 1 pseudocode
 3 documents

The code makes successfully on my Linux and Windows desktop systems.


GENERAL STRUCTURE OF CONNEL-USING PROGRAMS

Each program has a similar structure, based on the Wide Computing
principle that communication entities should be on the outside. The
one concession is the connel_create capability, which (usually in
server/client cases) permits one of the programs (usually the first to
start running) to create a real connector link ("real connel"), for
instance a socket or named pipe. After this, the real connel exists
outside the creating program and is accessible to it and to other
communicating programs.

Besides that create anomaly, the design is for the program to pick up
communication entities and use them. A list of these entities is
declared, they are opened, used, and closed at the end. The use can be
one of two ways. If unconditional, and there is no need to do other
work while waiting for communication, standard read, write, and sleep
calls are used.

If multiple-stimulus select is needed (the more common case), then a
further level of entities is used. A set of machines, which are
unidirectional connel handles, is defined and from time to time listened
to, so that whatever communication or stimulus happens first can be
immediately dealt with. This select-like capability is a necessary
primitive of Wide Computing.

Timers are available, both unconditionally and in the select machine
capability. A microsecond resolution is offered, but actual resolution
depends on the hardware and operating system.


CURRENT MAIN LIBRARY CALLS

None of the connel calls does a malloc, and so lists and structs are
expected to be pre-declared by the calling program. A distinction is
made between connector links, which may be bidirectional, and machines,
which are always unidirectional and are usable in select or its
Windows equivalents like WaitForMultipleObjects. A distinction is also
made between connel structs, which are merely spaces in memory, and
real connels, which are entities capable of doing real communication.

Finally, creation from within the program is not always possible. Some
real connels pre-exist (such as serial connections), and some may
either pre-exist or be created in-program (such as named pipes or
sockets). The connel_create applies only to the latter case, and if it
is called, will be called only by one of a communicating pair or set
of programs. The absolutely pre-existing real connels must be brought
up by operating system manipulations before running the programs.

 connel_list_init      initializes a list of connector links (connels)
 connel_begin          initializes one connel struct, adds it to list
 connel_end            undoes connel_begin

 connel_create         creates a real connel
 connel_open           opens a real connel
 connel_close          undoes connel_open

 connel_read           reads from a connel
 connel_write          writes to a connel

 connel_set_init       initializes a set of machines (select handles)
 connel_machine_begin  initializes one machine from a connel
 connel_machine_add    adds one machine to a set
 connel_machine_listen enables select to listen to one machine
 connel_machine_deafen undoes connel_machine_listen
 connel_machine_end    undoes connel_machine_begin

 connel_timeout_init   initializes a time struct to INFINITE
 connel_timebase       finds current time (in microseconds)
 connel_timeadd        adds time
 connel_timesub        subtracts time
 connel_sleep          sleeps a length of time

 connel_connect_start  (server) triggers asynchronous connect
 connel_read_start     triggers asynchronous read for select
 connel_select         triggers a select