You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@apr.apache.org by Aaron Bannert <aa...@clove.org> on 2002/01/11 20:50:07 UTC
[PROPOSAL] apr_spipe_t - stream pipe IPC mechanism
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.
-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 */
Re: [PROPOSAL] apr_spipe_t - stream pipe IPC mechanism
Posted by jean-frederic clere <jf...@fujitsu-siemens.com>.
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 */