[thrift] spruce up Erlang binding for tonight's release
Summary:
* got rid of most of the otp_base jonx ... save that for a future release unfortunately
* cleaned up the tutorial server, added -erl to tutorial.thrift's shebang
* made better README and TODO
Test Plan: checked out a copy, read my directions, built and ran the tutorial, and pretended that it didn't blow
git-svn-id: https://svn.apache.org/repos/asf/incubator/thrift/trunk@665273 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/lib/erl/README b/lib/erl/README
index 84211bd..caea067 100644
--- a/lib/erl/README
+++ b/lib/erl/README
@@ -1,68 +1,82 @@
-Much more information on these topics can be found at www.erlware.org
+Thrift Erlang Library
+README Author: Chris Piro (cpiro@facebook.com)
+Last Modified: 2007-Sep-17
-Building the tree
-=================
+Thrift is distributed under the Thrift open source software license.
+Please see the included LICENSE file.
-To build, type make, it should all work from there.
+Using Thrift with Erlang
+========================
-NOTE** if your system has erlang installed in a directory other than /usr/local/lib/erlang
-then you must set the environment variable ERL_RUN_TOP to that directory. For example
-if you have erlang installed in /home/jdoe/erlang then you should
-export ERL_RUN_TOP=/home/jdoe/erlang
+The Thrift Erlang binding is built using GNU make. Run `make' in
+lib/erl to generate the necessary .beam object files in lib/erl/ebin/.
+Although the directories are laid out much like an OTP application,
+these bindings (as you will soon discover) are not an OTP application
+proper. When starting the Erlang emulator (interpreter) you must use
+`-pa /path/to/thrift/lib/erl/ebin' to load the bindings.
+Running the Tutorial
+====================
-Creating a new application
-==========================
+It is recommended to pattern your own servers after the tutorial
+included in tutorial/. Generate the gen-erl/ directory by running
+tutorial.thrift, then cd to tutorial/erl/ and run server.sh. This
+script includes the commmands necessary to compile the generated
+Erlang source, compile the tutorial server itself, and open the Erlang
+emulator. At the emulator prompt, type `server:start()' to begin
+listening for connections.
-A new application can be created by using the appgen utility in otp/tools/utilities.
-This utility will create a basic OTP app framework under the otp/lib directory and
-an OTP release under the otp/release directory.
+Note that there is no tutorial client; you may use a supplied client
+in another language.
-usage: appgen <appname> <prefix>
+Implementation Notes
+====================
-Appname is the name of the application that you would like to create. The prefix is
-usually the first letter of each word in the appname. This prefix is to avoid name
-clashes between applications included in a release (Erlang does not have packages).
+tExecptions and t*Factorys are straight "new" -- e.g. TF =
+tTransportFactory:new() everything else is start_new
+(i.e. gen_server:start_link) -- this spawns a process and returns a
+pid
-example usage: appgen my_app ma
+tErlProcessor is a shim around the generated code (which is not
+actually a gen_server). Of course tErlProcessor isn't a gen_server
+either ... thrift_oop_server is a shim to make our "Thrift objects"
+gen_servers. Maybe we should remove some layers?
-which results in
+get/set never means process dictionary
-otp/lib/my_app & otp/release/my_app_rel
+Use tErlServer and tErlAcceptor. tSimpleServer and tServerSocket as
+are present in the other bindings are incompatible by design ... the
+call trace is spastic across the process tree. tErlServer and
+tErlAcceptor follow the same model as iserve:
-Running a release
-=================
+ * the top level code spawns a tErlServer, which listens on a socket
+ * a tErlAcceptor is spawned and calls accept() on the listening
+socket
+ * when accept() finishes, the tErlAcceptor
+ * tells the tErlServer to spawn a new acceptor
+ * handles the requests by spawning a processor, a transport, and a
+protocol
+ * (the tricky part) when the socket closes, the protocol exits, so:
+ * the transport exits because it's the one caller of the protocol
+ * likewise, the processor exits because it's the caller of the
+transport
+ * the tErlAcceptor traps the protocol's exit and exits with an
+acceptor_done
+ * the tErlServer sees that the acceptor exited and does nothing
+since there is already another acceptor accept()ing on the listen
+socket
-Your release should contain all that you need to run your application. If your application
-depends on any applications that are supplied outside of this build tree or OTP itself then
-they may be added to the <appname>_rel.rel.src file. If the extra applications are present
-in this build tree then they will be found by the make process and included in the final
-release.
+For info about iserve: http://www.trapexit.org/A_fast_web_server_demonstrating_some_undocumented_Erlang_features
-To run a release there are two options: "local" and installed. The local version can be found
-in the otp/release/<appname>_rel/local directory which is added by the make process. This
-should be used during development to run your release interactively via an Erlang shell.
-To run a release in local mode cd into the "local" directory and run <appname>_rel.sh.
+Final Thoughts
+==============
-The second way to run a release is to install it and run it as a daemon. This is used for
-applications in a production setting. To do this you need to first run make & make install
-from the <appname>_rel directory. This will place a complete production ready versioned
-release in the /usr/local/lib/ directory under <appname>_rel. To run an installed release
-cd to /usr/local/lib/<appname>_rel/release/<rel_vsn> and run <appname>_rel.sh.
-
-In the case where you want to create a production ready release on one machine and then deploy it
-on multiple identical machines you may create a production tar archive. To do this run
-make & make tar from the otp/release/<appname>_rel/ directory. This will create a tar file conataining
-the release name and version number in the file name. This tar can be shipped to its destination and
-untarred. Within the untarred directory there is a shell script entitled install.sh. Running this
-script will install the release by default in /usr/local/lib/<appname>_rel. An optional argument
-can be provided that will direct the installation to a different directory.
-
-Example install.sh /opt/lib
-
-This will install the release in /opt/lib/<appname>_rel
-
-
-
-
+This binding is a work in progress. It's certainly less thoroughly
+tested than the other, older bindings. Despite using parts from
+otp_base it is not packaged well, nor is it an OTP application (not to
+mention its many smaller transgressions). This implementation
+intentionally patterns after the other bindings (which is why there's
+oop.erl and thrift_oop_server), but regretfully it departs from
+idiomatic Erlang. Please see the included TODO and contribute your
+improvements back to the project.