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 [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 */
