apr-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jean-frederic clere <jfrederic.cl...@fujitsu-siemens.com>
Subject Re: [PROPOSAL] apr_spipe_t - stream pipe IPC mechanism
Date Mon, 14 Jan 2002 10:20:05 GMT
Aaron Bannert wrote:
> 
> A stream pipe is a full-duplex pipe that can be used to communicate data,
> file descriptors and socket descriptors. When one of the pairs is used
> in a parent process and another in a child process it allows a form of
> interprocess communication. [straight from my apr_spipe_create comment]
> 
> The main features of this API are:
> 
> - datagram-style delivery of data and metadata (as a bundle)
> - can pass data efficiently, if possible (it prefers iovec)
> - can pass apr_file_t and apr_socket_t types
> 
> The main use case for this API is to make the perchild MPM portable
> to platforms other than Linux.
> 
> The name apr_spipe_t was chosen over something more broad, like
> apr_ipc_t because the author believes this name more accurately
> describes a type of IPC, in a world where we may implement other
> forms of IPC later.

Could this be extented to process that are not son processes? - AF_UNIX sockets
allow it -

> 
> -aaron
> 
> /* ====================================================================
>  * The Apache Software License, Version 1.1
>  *
>  * Copyright (c) 2000-2001 The Apache Software Foundation.  All rights
>  * reserved.
>  *
>  * Redistribution and use in source and binary forms, with or without
>  * modification, are permitted provided that the following conditions
>  * are met:
>  *
>  * 1. Redistributions of source code must retain the above copyright
>  *    notice, this list of conditions and the following disclaimer.
>  *
>  * 2. Redistributions in binary form must reproduce the above copyright
>  *    notice, this list of conditions and the following disclaimer in
>  *    the documentation and/or other materials provided with the
>  *    distribution.
>  *
>  * 3. The end-user documentation included with the redistribution,
>  *    if any, must include the following acknowledgment:
>  *       "This product includes software developed by the
>  *        Apache Software Foundation (http://www.apache.org/)."
>  *    Alternately, this acknowledgment may appear in the software itself,
>  *    if and wherever such third-party acknowledgments normally appear.
>  *
>  * 4. The names "Apache" and "Apache Software Foundation" must
>  *    not be used to endorse or promote products derived from this
>  *    software without prior written permission. For written
>  *    permission, please contact apache@apache.org.
>  *
>  * 5. Products derived from this software may not be called "Apache",
>  *    nor may "Apache" appear in their name, without prior written
>  *    permission of the Apache Software Foundation.
>  *
>  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
>  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
>  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
>  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
>  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
>  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
>  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
>  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
>  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
>  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
>  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
>  * SUCH DAMAGE.
>  * ====================================================================
>  *
>  * This software consists of voluntary contributions made by many
>  * individuals on behalf of the Apache Software Foundation.  For more
>  * information on the Apache Software Foundation, please see
>  * <http://www.apache.org/>.
>  */
> 
> #ifndef APR_SPIPE_H
> #define APR_SPIPE_H
> 
> #include "apr.h"
> #include "apr_file_io.h"
> #include "apr_network_io.h"
> #include "apr_pools.h"
> #include "apr_errno.h"
> 
> #ifdef __cplusplus
> extern "C" {
> #endif /* __cplusplus */
> 
> /**
>  * @file apr_spipe.h
>  * @brief APR Stream Pipe Routines
>  */
> 
> /**
>  * @defgroup APR_SPIPE Stream Pipe Routines
>  * @ingroup APR
>  * @{
>  */
> 
> #define APR_SPIPE_BLOCK     0x1
> #define APR_SPIPE_NONBLOCK  0x2
> 
> /**
>  * Private, platform-specific data struture representing a stream pipe.
>  */
> typedef struct apr_spipe_t apr_spipe_t;
> 
> /**
>  * Enumeration of the types of metadata that can be passed over a
>  * stream pipe.
>  */
> typedef enum {
>     APR_SPIPE_NONE   = 0,
>     APR_SPIPE_FILE   = 1,
>     APR_SPIPE_SOCKET = 2
> } apr_spipe_msg_type_e;
> 
> /**
>  * Types of metadata that we can transfer across a stream pipe.
>  * This is a union because we only want to pass one at a time.
>  */
> typedef union {
>     apr_file_t   *file;        /* file descriptor to pass across pipe */
>     apr_socket_t *sock;        /* socket descriptor to pass across pipe */
> } apr_spipe_msg_metadata_u;
> 
> /**
>  * Structure of a message that can be passed over a stream pipe.
>  * The major fields are optional, and may be NULL.
>  */
> typedef struct {
>     struct iovec *msg_iov;     /* scatter/gather array, from struct msghdr */
>     apr_size_t    msg_iovlen;  /* # elements in msg_iov, from struct msghdr */
>     apr_spipe_msg_metadata_u metadata; /* Optional Metadata */
>     apr_spipe_msg_type_e metatype; /* Type of the metadata */
> } apr_spipe_msg_t;
> 
> /**
>  * Create and initialize a stream pipe pair. A stream pipe is a
>  * full-duplex pipe that can be used to communicate data, file
>  * descriptors and socket descriptors. When one of the pairs
>  * is used in a parent process and another in a child process it
>  * allows a form of interprocess communication.
>  * @param spipe1 the memory address where the first newly created
>  *        stream pipe will be stored.
>  * @param spipe2 the memory address where the second newly created
>  *        stream pipe will be stored.
>  * @param flags placeholder for future flags, currently none.
>  * @param pool the pool from which to allocate the stream pipes.
>  */
> APR_DECLARE(apr_status_t) apr_spipe_create(apr_spipe_t **spipe1,
>                                            apr_spipe_t **spipe2,
>                                            apr_int32_t flags,
>                                            apr_pool_t *pool);
> 
> /**
>  * Send data over a stream pipe.
>  * @param spipe the stream pipe where the data is to be sent.
>  * @param msg a message struct containing the fields that are passed across
>  *            the pipe.
>  * @param flags set the BLOCK/NONBLOCK status of this send call.
>  */
> APR_DECLARE(apr_status_t) apr_spipe_send(apr_spipe_t *spipe,
>                                          apr_spipe_msg_t *msg,
>                                          apr_int32_t flags);
> 
> /**
>  * Receive data from a stream pipe.
>  * @param spipe the stream pipe from where the data is to be received.
>  * @param msg a message struct that is used to receive fields from across
>  *            the pipe.
>  * @param flags set the BLOCK/NONBLOCK status of this recv call.
>  * @param pool a pool from where to allocate the message struct fields.
>  */
> APR_DECLARE(apr_status_t) apr_spipe_recv(apr_spipe_t *spipe,
>                                          apr_spipe_msg_t *msg,
>                                          apr_int32_t flags,
>                                          apr_pool_t *pool);
> 
> /**
>  * Destroy the stream pipes and free the memory associated with each.
>  * @param spipe1 the first stream pipe to destroy (may be NULL).
>  * @param spipe2 the second stream pipe to destroy (may be NULL).
>  */
> APR_DECLARE(apr_status_t) apr_spipe_destroy(apr_spipe_t *spipe1,
>                                             apr_spipe_t *spipe2);
> 
> /**
>  * Get the pool used by this stream pipe.
>  * @param spipe the stream pipe from where to retrieve the pool.
>  * @return apr_pool_t the pool
>  */
> APR_POOL_DECLARE_ACCESSOR(spipe);
> 
> #ifdef __cplusplus
> }
> #endif
> 
> #endif  /* APR_SPIPE_H */

Mime
View raw message