avro-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cutt...@apache.org
Subject svn commit: r778820 - in /hadoop/avro/trunk: ./ src/c/ src/c/docs/ src/doc/content/xdocs/
Date Tue, 26 May 2009 18:02:48 GMT
Author: cutting
Date: Tue May 26 18:02:47 2009
New Revision: 778820

URL: http://svn.apache.org/viewvc?rev=778820&view=rev
Log:
AVRO-37.  Add C API docs.  Contributed by Matt Massie.

Added:
    hadoop/avro/trunk/src/c/avro_array.c
    hadoop/avro/trunk/src/c/docs/
    hadoop/avro/trunk/src/c/docs/doxygen.conf
Modified:
    hadoop/avro/trunk/CHANGES.txt
    hadoop/avro/trunk/README.txt
    hadoop/avro/trunk/build.xml
    hadoop/avro/trunk/src/c/.gitignore
    hadoop/avro/trunk/src/c/Makefile.am
    hadoop/avro/trunk/src/c/avro.h
    hadoop/avro/trunk/src/c/avro_file.c
    hadoop/avro/trunk/src/c/avro_socket.c
    hadoop/avro/trunk/src/c/test_avro_float_double.c
    hadoop/avro/trunk/src/doc/content/xdocs/site.xml

Modified: hadoop/avro/trunk/CHANGES.txt
URL: http://svn.apache.org/viewvc/hadoop/avro/trunk/CHANGES.txt?rev=778820&r1=778819&r2=778820&view=diff
==============================================================================
--- hadoop/avro/trunk/CHANGES.txt (original)
+++ hadoop/avro/trunk/CHANGES.txt Tue May 26 18:02:47 2009
@@ -45,6 +45,8 @@
 
     AVRO-34. Upgrade to Jackson version 1.0.0.  (cutting)
 
+    AVRO-37. Add C api docs.  Also link to py docs.  (Matt Massie & cutting)
+
   OPTIMIZATIONS
 
   BUG FIXES

Modified: hadoop/avro/trunk/README.txt
URL: http://svn.apache.org/viewvc/hadoop/avro/trunk/README.txt?rev=778820&r1=778819&r2=778820&view=diff
==============================================================================
--- hadoop/avro/trunk/README.txt (original)
+++ hadoop/avro/trunk/README.txt Tue May 26 18:02:47 2009
@@ -15,7 +15,7 @@
 
  - Java 1.6
  - Python 2.5 or greater
- - gcc, automake, libtool, libapr1-dev, libaprutil1-dev
+ - gcc, automake, libtool, libapr1-dev, libaprutil1-dev, doxygen
  - Apache Ant 1.7
  - Apache Forrest 0.8 (for documentation, requires Java 1.5)
 

Modified: hadoop/avro/trunk/build.xml
URL: http://svn.apache.org/viewvc/hadoop/avro/trunk/build.xml?rev=778820&r1=778819&r2=778820&view=diff
==============================================================================
--- hadoop/avro/trunk/build.xml (original)
+++ hadoop/avro/trunk/build.xml Tue May 26 18:02:47 2009
@@ -40,7 +40,8 @@
 
   <property name="build.classes" value="${build.dir}/classes"/>
   <property name="build.doc" value="${build.dir}/doc"/>
-  <property name="build.javadoc" value="${build.doc}/api"/>
+  <property name="build.javadoc" value="${build.doc}/api/java"/>
+  <property name="build.cdoc" value="${build.doc}/api/c"/>
 
   <exec executable="sed" inputstring="${os.name}" outputproperty="nonspace.os">
      <arg value="s/ /_/g"/>
@@ -363,16 +364,16 @@
     <taskdef name="py-doc" classname="org.pyant.tasks.PythonDocTask">
       <classpath refid="java.classpath" />
     </taskdef>
-    <mkdir dir="${build.doc}/py"/>
+    <mkdir dir="${build.doc}/api/py"/>
     <py-doc python="python" pythonpathref="test.py.path" defaultexcludes="true"
-       destdir="${build.doc}/py">
+       destdir="${build.doc}/api/py">
       <fileset dir="${basedir}/src/py">
         <include name="**/*"/>
       </fileset>
     </py-doc>
   </target>
 
-  <target name="doc" depends="forrest.check,javadoc" description="Generate forrest-based
documentation. To use, specify -Dforrest.home=&lt;base of Apache Forrest installation&gt;
on the command line." if="forrest.home">
+  <target name="doc" depends="forrest.check,javadoc,pydoc,cdoc" description="Generate
forrest-based documentation. To use, specify -Dforrest.home=&lt;base of Apache Forrest
installation&gt; on the command line." if="forrest.home">
     <exec executable="${forrest.home}/bin/forrest" failonerror="true">
       <env key="JAVA_HOME" value="${java5.home}"/>
       <arg value="-Dproject.content-dir=src/doc"/>
@@ -418,7 +419,6 @@
     <mkdir dir="${dist.dir}"/>
     <mkdir dir="${dist.dir}/lib"/>
     <mkdir dir="${dist.dir}/doc"/>
-    <mkdir dir="${dist.dir}/doc/api"/>
 
     <copy todir="${dist.dir}/lib" includeEmptyDirs="false">
       <fileset dir="lib"/>
@@ -480,6 +480,12 @@
   </target>
 
   <!-- C Targets -->
+  <target name="cdoc">
+  <exec dir="${c.src.dir}" executable="env" failonerror="true">
+     <arg line="C_DOCS_OUTPUT=${build.cdoc} make docs" />
+  </exec>
+  </target>
+
   <target name="autoreconf-c-check">
     <uptodate targetfile="${c.src.dir}/configure"
 	      srcfile="${c.src.dir}/configure.in"

Modified: hadoop/avro/trunk/src/c/.gitignore
URL: http://svn.apache.org/viewvc/hadoop/avro/trunk/src/c/.gitignore?rev=778820&r1=778819&r2=778820&view=diff
==============================================================================
--- hadoop/avro/trunk/src/c/.gitignore (original)
+++ hadoop/avro/trunk/src/c/.gitignore Tue May 26 18:02:47 2009
@@ -16,3 +16,4 @@
 config.h
 autom4te.cache
 test_avro_*[!.][!c]
+INSTALL

Modified: hadoop/avro/trunk/src/c/Makefile.am
URL: http://svn.apache.org/viewvc/hadoop/avro/trunk/src/c/Makefile.am?rev=778820&r1=778819&r2=778820&view=diff
==============================================================================
--- hadoop/avro/trunk/src/c/Makefile.am (original)
+++ hadoop/avro/trunk/src/c/Makefile.am Tue May 26 18:02:47 2009
@@ -1,4 +1,5 @@
 AM_CFLAGS=$(APR_CFLAGS) $(APR_INCLUDES) $(APU_INCLUDES) -Wall -pedantic
+C_DOCS_OUTPUT ?= "docs/dox"
 
 include_HEADERS = avro.h
 
@@ -28,6 +29,11 @@
 TESTS=$(check_PROGRAMS)
 
 pretty:
-	indent *.c *.h
+	indent *.c
+
+docs:
+	@(cat docs/doxygen.conf; echo "OUTPUT_DIRECTORY=$(C_DOCS_OUTPUT)")| doxygen -
+
+.PHONY: docs
 
 CLEANFILES=*~

Modified: hadoop/avro/trunk/src/c/avro.h
URL: http://svn.apache.org/viewvc/hadoop/avro/trunk/src/c/avro.h?rev=778820&r1=778819&r2=778820&view=diff
==============================================================================
--- hadoop/avro/trunk/src/c/avro.h (original)
+++ hadoop/avro/trunk/src/c/avro.h Tue May 26 18:02:47 2009
@@ -1,5 +1,11 @@
 #ifndef AVRO_H
 #define AVRO_H
+
+/**
+@file avro.h
+@brief AVRO API
+*/
+
 #include <stdarg.h>
 #include <stdint.h>
 #include <sys/types.h>
@@ -7,16 +13,19 @@
 #include <apr_file_io.h>
 #include <apr_network_io.h>
 
-/*! \mainpage Avro C Documentation
-*
-* \section intro_sec Introduction
-* 
-* This is the introduction.
-*
-* \section install_sec Installation
-*
-* This is the installation section.
-*
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+@defgroup AVRO Avro C API
+@{
+*/
+
+/**
+* @defgroup Handle_Routines AVRO Handles
+* @ingroup AVRO
+* @{
 */
 
 /**
@@ -33,7 +42,7 @@
 /**
 Avro status enum.
 Enum used by Avro functions to return state.
-TODO: expand the number of states
+@todo expand the number of states
 */
 enum avro_status_t
 {
@@ -46,7 +55,7 @@
 /**
 Avro handle.
 Opaque handle for encoding/decoding data to memory, file or network.
-@warning Never operate on an Avro handle directly
+@warning Never operate on an Avro handle directly.  Use the AVRO Handle routines instead.
 */
 struct AVRO
 {
@@ -66,11 +75,11 @@
   } *a_ops;
   apr_pool_t *pool; /**< Pool used for allocating memory for dynamic data structures */
 
-  apr_file_t *file;
-  apr_socket_t *socket;
-  caddr_t addr;
-  int64_t len;
-  int64_t used;
+  apr_file_t *file; /**< Used by the file-backed handle */
+  apr_socket_t *socket;	/**< Used by the socket-backed handle */
+  caddr_t addr;	/**< Used by the memory-backed handle */
+  int64_t len;	/**< Used by the memory-backed handle */
+  int64_t used;	/**< Used by the memory-backed handle */
 };
 typedef struct AVRO AVRO;
 
@@ -91,23 +100,112 @@
 avro_status_t avro_create_memory (AVRO * avro, apr_pool_t * pool,
 				  caddr_t addr, int64_t len, avro_op op);
 
+/** Create a file-backed Avro handle
+@param avro Pointer to the handle that will be initialized 
+@param pool Pool used for allocating dynamic data structures
+@param file The file to read(decode) or write(encode) from
+@param op Expresses the operation the handle should perform (e.g. encode, decode)
+@return The Avro status
+*/
 avro_status_t avro_create_file (AVRO * avro, apr_pool_t * pool,
 				apr_file_t * file, avro_op op);
+
+/** Create a socket-backed Avro handle
+@param avro Pointer to the handle that will be initialized
+@param pool Pool used for allocating dynamic data structures
+@param socket The socket to read(decode) or write(encode) from
+@param op Expresses the operation the handle should perform (e.g. encode, decode)
+@return The Avro status
+*/
 avro_status_t avro_create_socket (AVRO * avro, apr_pool_t * pool,
 				  apr_socket_t * socket, avro_op op);
+/** @} */
 
 typedef avro_status_t (*avroproc_t) (AVRO, void *, ...);
 typedef int bool_t;
 
+/**
+* @defgroup Primitives AVRO Primitive Type Serialization
+* @ingroup AVRO
+* @{
+*/
+
+/** avro_null() will not read or write any data 
+*/
 avro_status_t avro_null (void);
+
+/** avro_int64() is called to read/write a 64-bit signed integer
+@param avro The Avro handle
+@param lp Pointer to the 64-bit integer
+@return The Avro status
+*/
 avro_status_t avro_int64 (AVRO * avro, int64_t * lp);
+
+/** avro_string() is called to read/write a string
+@param avro The Avro handle
+@param str Pointer to the string
+@param maxlen The maximum length of the string to read/write
+@return The Avro status
+*/
 avro_status_t avro_string (AVRO * avro, char **str, int64_t maxlen);
+
+/** avro_bytes() is called to read/write opaque bytes
+@param avro The Avro handle
+@param bytes The pointer to the bytes to read/write
+@param len Pointer to an integer which either (1) expresses the 
+number of bytes you wish to encode or (2) is set on return to
+give the number of bytes decoded
+@param maxlen The maximum number of bytes to read/write
+@return The Avro status
+*/
 avro_status_t avro_bytes (AVRO * avro, char **bytes, int64_t * len,
 			  int64_t maxlen);
+
+/** avro_bool() is called to read/write a boolean value
+@param avro The Avro handle
+@param bp Pointer to the boolean pointer
+@return The Avro status
+*/
 avro_status_t avro_bool (AVRO * avro, bool_t * bp);
+
+/** avro_float() is called to read/write a float
+@param avro The Avro handle
+@param fp Pointer to the float 
+@return The Avro status
+*/
 avro_status_t avro_float (AVRO * avro, float *fp);
+
+/** avro_double() is called to read/write a double
+@param avro The Avro handle
+@param dp Pointer to the double
+@return The Avro status
+*/
 avro_status_t avro_double (AVRO * avro, double *dp);
 
+/** @} */
+
+/**
+* @defgroup Compound AVRO Compound Type Serialization
+* @ingroup AVRO
+* @{
+*/
+
+/** avro_array() encodes/decodes an array of avro elements
+@param avro The Avro handle
+@param addrp Pointer to the array
+@param sizep Pointer to the number of elements
+@param maxsize The maximum number of Avro elements
+@param elsize The size in bytes of each element
+@param elproc The Avro routine to handle each element
+@return The Avro status
+*/
+avro_status_t avro_array (AVRO * avro, caddr_t * addrp, uint32_t * sizep,
+			  uint32_t maxsize, uint32_t elsize,
+			  avroproc_t elproc);
+
+/** @} */
+
+
 /* Useful for debugging */
 void avro_dump_memory (AVRO * avro, FILE * fp);
 
@@ -116,4 +214,10 @@
 avro_status_t avro_getint64_raw (AVRO * avro, int64_t * value);
 avro_status_t avro_putint64_raw (AVRO * avro, const int64_t value);
 
+/** @} */
+
+#ifdef __cplusplus
+}
 #endif
+
+#endif /* ifdef AVRO_H */

Added: hadoop/avro/trunk/src/c/avro_array.c
URL: http://svn.apache.org/viewvc/hadoop/avro/trunk/src/c/avro_array.c?rev=778820&view=auto
==============================================================================
--- hadoop/avro/trunk/src/c/avro_array.c (added)
+++ hadoop/avro/trunk/src/c/avro_array.c Tue May 26 18:02:47 2009
@@ -0,0 +1,10 @@
+#include "avro.h"
+
+avro_status_t
+avro_array (AVRO * avro, caddr_t * addrp, uint32_t * sizep,
+	    uint32_t maxsize, uint32_t elsize, avroproc_t elproc)
+{
+
+
+  return AVRO_OK;
+}

Modified: hadoop/avro/trunk/src/c/avro_file.c
URL: http://svn.apache.org/viewvc/hadoop/avro/trunk/src/c/avro_file.c?rev=778820&r1=778819&r2=778820&view=diff
==============================================================================
--- hadoop/avro/trunk/src/c/avro_file.c (original)
+++ hadoop/avro/trunk/src/c/avro_file.c Tue May 26 18:02:47 2009
@@ -1,5 +1,66 @@
+#include "avro.h"
+#include <string.h>
+#include "dump.h"
 
+/**
+@todo We could likely speedup file i/o by reading ahead
+*/
+static avro_status_t
+file_get_bytes (struct AVRO *avro, caddr_t addr, const int64_t len)
+{
+  apr_status_t apr_status;
+  if ((avro->len - avro->used) < len || len < 0)
+    {
+      return AVRO_FAILURE;
+    }
+  if (len > 0)
+    {
+      apr_status =
+	apr_file_read_full (avro->file, addr, (apr_size_t) len, NULL);
+      if (apr_status != APR_SUCCESS)
+	{
+	  return AVRO_FAILURE;
+	}
+    }
+  return AVRO_OK;
+}
 
+static avro_status_t
+file_put_bytes (struct AVRO *avro, const char *addr, const int64_t len)
+{
+  apr_status_t apr_status;
+  if ((avro->len - avro->used) < len || len < 0)
+    {
+      return AVRO_FAILURE;
+    }
+  if (len > 0)
+    {
+      apr_status =
+	apr_file_write_full (avro->file, addr, (apr_size_t) len, NULL);
+      if (apr_status != APR_SUCCESS)
+	{
+	  return AVRO_FAILURE;
+	}
+    }
+  return AVRO_OK;
+}
 
+static const struct avro_ops avro_file_ops = {
+  file_get_bytes,
+  file_put_bytes
+};
 
-
+avro_status_t
+avro_create_file (AVRO * avro, apr_pool_t * pool, apr_file_t * file,
+		  avro_op op)
+{
+  if (!avro || !pool || !file)
+    {
+      return AVRO_FAILURE;
+    }
+  avro->pool = pool;
+  avro->a_op = op;
+  avro->a_ops = (struct avro_ops *) &avro_file_ops;
+  avro->file = file;
+  return AVRO_OK;
+}

Modified: hadoop/avro/trunk/src/c/avro_socket.c
URL: http://svn.apache.org/viewvc/hadoop/avro/trunk/src/c/avro_socket.c?rev=778820&r1=778819&r2=778820&view=diff
==============================================================================
--- hadoop/avro/trunk/src/c/avro_socket.c (original)
+++ hadoop/avro/trunk/src/c/avro_socket.c Tue May 26 18:02:47 2009
@@ -1,6 +1,83 @@
-
-
-
-
-
-
+#include "avro.h"
+#include <string.h>
+#include "dump.h"
+
+static avro_status_t
+socket_get_bytes (struct AVRO *avro, caddr_t addr, const int64_t len)
+{
+  apr_status_t apr_status;
+  if ((avro->len - avro->used) < len || len < 0)
+    {
+      return AVRO_FAILURE;
+    }
+  if (len > 0)
+    {
+      /* TODO: len can overflow an apr_size_t */
+      apr_size_t bytes_wanted = len;
+      apr_size_t bytes_recvd = 0;
+      while (bytes_recvd < bytes_wanted)
+	{
+	  apr_size_t bytes_requested = bytes_wanted - bytes_recvd;
+	  apr_status = apr_socket_recv (avro->socket, addr, &bytes_requested);
+	  if (apr_status != APR_SUCCESS)
+	    {
+	      return AVRO_FAILURE;
+	    }
+	  bytes_recvd += bytes_requested;
+	}
+    }
+  return AVRO_OK;
+}
+
+static avro_status_t
+socket_put_bytes (struct AVRO *avro, const char *addr, const int64_t len)
+{
+  apr_status_t apr_status;
+  if ((avro->len - avro->used) < len || len < 0)
+    {
+      return AVRO_FAILURE;
+    }
+  if (len > 0)
+    {
+      /* TODO: len can overflow an apr_size_t */
+      apr_size_t bytes_wanted = len;
+      apr_size_t bytes_sent = 0;
+      while (bytes_sent < bytes_wanted)
+	{
+	  apr_size_t bytes_requested = bytes_wanted - bytes_sent;
+	  apr_status = apr_socket_send (avro->socket, addr, &bytes_requested);
+	  if (apr_status != APR_SUCCESS)
+	    {
+	      return AVRO_FAILURE;
+	    }
+	  bytes_sent += bytes_requested;
+	}
+    }
+  return AVRO_OK;
+}
+
+static const struct avro_ops avro_socket_ops = {
+  socket_get_bytes,
+  socket_put_bytes
+};
+
+avro_status_t
+avro_create_socket (AVRO * avro, apr_pool_t * pool, apr_socket_t * socket,
+		    avro_op op)
+{
+  if (!avro || !pool || !socket)
+    {
+      return AVRO_FAILURE;
+    }
+  avro->pool = pool;
+  avro->a_op = op;
+  avro->a_ops = (struct avro_ops *) &avro_socket_ops;
+  avro->socket = socket;
+  return AVRO_OK;
+}
+
+void
+avro_dump_socket (AVRO * avro, FILE * fp)
+{
+  dump (fp, avro->addr, avro->used);
+}

Added: hadoop/avro/trunk/src/c/docs/doxygen.conf
URL: http://svn.apache.org/viewvc/hadoop/avro/trunk/src/c/docs/doxygen.conf?rev=778820&view=auto
==============================================================================
--- hadoop/avro/trunk/src/c/docs/doxygen.conf (added)
+++ hadoop/avro/trunk/src/c/docs/doxygen.conf Tue May 26 18:02:47 2009
@@ -0,0 +1,24 @@
+PROJECT_NAME="AVRO C API"
+
+INPUT=.
+QUIET=YES
+RECURSIVE=YES
+FILE_PATTERNS=*.h
+
+#OUTPUT_DIRECTORY=docs/dox
+
+MACRO_EXPANSION=YES
+EXPAND_ONLY_PREDEF=YES
+#EXPAND_AS_DEFINED=
+#PREDEFINED
+
+OPTIMIZE_OUTPUT_FOR_C=YES
+STRIP_CODE_COMMENTS=NO
+
+FULL_PATH_NAMES=NO
+CASE_SENSE_NAMES=NO
+#STRIP_FROM_PATH=
+
+EXCLUDE_PATTERNS=config.h dump.h error.h
+
+#GENERATE_TAGFILE=

Modified: hadoop/avro/trunk/src/c/test_avro_float_double.c
URL: http://svn.apache.org/viewvc/hadoop/avro/trunk/src/c/test_avro_float_double.c?rev=778820&r1=778819&r2=778820&view=diff
==============================================================================
--- hadoop/avro/trunk/src/c/test_avro_float_double.c (original)
+++ hadoop/avro/trunk/src/c/test_avro_float_double.c Tue May 26 18:02:47 2009
@@ -61,7 +61,7 @@
 	  err_quit ("Unable to decode AVRO float");
 	}
 
-      avro_status = avro_getint64_raw (&avro_out, &d_out);
+      avro_status = avro_getint64_raw (&avro_out, (int64_t*)&d_out);
       if (avro_status != AVRO_OK)
 	{
 	  err_quit ("Unable to decode AVRO double");

Modified: hadoop/avro/trunk/src/doc/content/xdocs/site.xml
URL: http://svn.apache.org/viewvc/hadoop/avro/trunk/src/doc/content/xdocs/site.xml?rev=778820&r1=778819&r2=778820&view=diff
==============================================================================
--- hadoop/avro/trunk/src/doc/content/xdocs/site.xml (original)
+++ hadoop/avro/trunk/src/doc/content/xdocs/site.xml Tue May 26 18:02:47 2009
@@ -42,9 +42,11 @@
   <docs label="Documentation"> 
     <overview   label="Overview"          href="index.html" />
     <spec       label="Specification"     href="spec.html" />
-    <api       label="API Docs"           href="ext:api/index" />
-    <wiki      label="Wiki"               href="ext:wiki" />
-    <faq       label="FAQ"                href="ext:faq" />
+    <c-api      label="C API"             href="ext:api/c/index" />
+    <java-api   label="Java API"          href="ext:api/java/index" />
+    <py-api     label="Python API"        href="ext:api/py/index" />
+    <wiki       label="Wiki"              href="ext:wiki" />
+    <faq        label="FAQ"               href="ext:faq" />
   </docs>
   
   <external-refs>
@@ -61,7 +63,15 @@
     <vint      href="http://lucene.apache.org/java/2_4_0/fileformats.html#VInt"/>
     <zigzag    href="http://code.google.com/apis/protocolbuffers/docs/encoding.html#types"/>
     <api href="api/">
-      <index href="index.html" />
+      <c href="c/">
+	<index href="html/index.html" />
+      </c>
+      <java href="java/">
+	<index href="index.html" />
+      </java>
+      <py href="py/">
+	<index href="avro.html" />
+      </py>
     </api>
   </external-refs>
  



Mime
View raw message