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 [EMAIL PROTECTED] > * > * 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 */
