You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@avro.apache.org by cu...@apache.org on 2009/05/26 20:02:48 UTC
svn commit: r778820 - in /hadoop/avro/trunk: ./ src/c/ src/c/docs/
src/doc/content/xdocs/
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=<base of Apache Forrest installation> 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=<base of Apache Forrest installation> 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>