TODO

TODO
----

come up with cleaner approach towards getting remote variables

__newindex implementation to set variables on remote side

deal better with link level errors, especially for serial where minimal
transmission guarantees are made

rpc.on_error (HANDLE, func)   <-- add option for handle 

pass functions to a remote function (maybe so we can pass local callbacks
to a remote function). thus we are tying together two function spaces?

handle circular refs in data structures when dumping. tag data structures as
we traverse them?

optimizations:
	* handling of numbers: s8,s16,s32,double - encoded in type
	* handling of string lengths (u8,u16,u32) - encoded in 1st byte
	* socket reading and writing stuff to use buffers, like FILEs, don't
	  use system calls all the time.
	  	do this: FILE *file = fdopen (sock,"wb"); ... ?

protocol for telling the client when the header or version is bad.

asyncronous client operation when no return arguments are expected.

check @@@'s

code review
	TRY and ENDTRY paired
	all resources freed on exception

doc:
	socket errors close the handle, can't refer to it anymore!
	all API inside C file

test:
	all error modes
	code coverage
	arg & reply stress testing
	saving and *restoring* _ERRORMESSAGE handler.
	resource freeing on exceptions.
	memory leaks

async mode:
	pass async flag in function call, so no return args passed
	when reading old async function return values, handle old errors??

OLD TODOS
---------

pass user data to a remote function (or as return values)? the write()
function apparently needs this

DONE
----

abstract link/transport layer to allow different transports to be used

implement serial support

allow calling functions which are not globals (i.e. ones registered on tables)

handle non-existance of the remote function. we need some convention around
LRF_call ... or a "verify existance of remote function" function.

when LRF_close called, how do we prevent the user from using the handle again
- we can't, but at least prevent crashes or flag errors. the handle object
should have:
	* state indicator (connected, closed)
	* a lua GC tidyup routine

timeouts for expecting function return values --> just rely on standard
socket timeouts and the errors they generate.

implement "keepalive" option, i.e. more than one function call per connection.

error handling
	* handle all socket and protocol errors
	* use exception handling
	* make sure exception throwing releases resources on the lua stack -
	  or does it need to? make sure all other resources are freed.
	* as we are pushing stuff on the stack (eg in the server), check that
	  we dont run out of stack space --> lua rutime error will be triggered
	  anyway, so this is ok.

handing of IP addresses, names.

better function calling syntax:
	handle.foo (1,2,3)
	if handle.foo != nil then function_exists...
handle["foo"] returns a temporary userdata object that contains the name.
when this obj is called as a function it sends the data.
	intermediate obj must call lua_ref, lua_unref

make it C not C++
	use setjmp/longjmp to do exceptions

FIXUP socket exception handling - use setjmp/longjmp stack?

error handling
	* propagate remote script errors to client --> rpc_on_error()
	* runtime instead of fatal errors in many places (e.g. socket stuff).
	  BUT make sure we always tidy up open sockets, memory etc on
	  exceptions.
	* should not panic as much.

server side "event handling", i.e. just handle one function at a time, so
server code can execute as well.

------------------------------------------------------------------------------
-- a better way?

once connection is opened, function calls can be made in both directions.
protocol:

	u8	call (0) or result (1)
	data...

call:
	make a call
	read the reply
	if reply is result, done
	if reply is another call,
		do_call
		return result

--

handle = rpc_listen (12345)

while 1 do
	if rpc_peek (handle) then
		rpc_dispatch (handle)
	else
		write ("doo de doo...\n")
	end
end

rpc_close (handle)		-- works for clients *and* servers


function rpc_server (port)
	rpc_listen (port);
	while 1 do
		rpc_dispatch()
	end
end

--

future:
	function references may be passed around.
	when function references are passed around, they contain info about
	which host/port the function lives on. calling that function opens up
	a connection and calls the function. thus - need to do away with the
	concept of handles.