resolved EAGAIN issue (for now); updated docs; add unit tests; miscellaneous code clean-up