ach.h

Go to the documentation of this file.

/* -*- mode: C; c-basic-offset: 4 -*- */
/* ex: set shiftwidth=4 tabstop=4 expandtab: */
/*
 * Copyright (c) 2008-2013, Georgia Tech Research Corporation
 * Copyright (C) 2015, Rice University
 * All rights reserved.
 *
 * Author(s): Neil T. Dantam <ntd@rice.edu>
 * Georgia Tech Humanoid Robotics Lab
 * Under Direction of Prof. Mike Stilman <mstilman@cc.gatech.edu>
 *
 *
 * This file is provided under the following "BSD-style" License:
 *
 *
 *   Redistribution and use in source and binary forms, with or
 *   without modification, are permitted provided that the following
 *   conditions are met:
 *
 *   * Redistributions of source code must retain the above copyright
 *     notice, this list of conditions and the following disclaimer.
 *
 *   * 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.
 *
 *   * Neither the name of the copyright holder the names of its
 *     contributors may be used to endorse or promote products derived
 *     from this software without specific prior written permission.
 *
 *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
 *   CONTRIBUTORS "AS IS" AND ANY EXPRESS 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 COPYRIGHT HOLDER OR
 *   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.
 *
 */

/*
 * Shared Memory Layout:
 *
 *    ________
 *   | Header |
 *   |--------|
 *   | GUARDH |
 *   |--------|
 *   | Index  |
 *   |        |
 *   |        |
 *   |--------|
 *   | GUARDI |
 *   |--------|
 *   |  Data  |
 *   |        |
 *   |        |
 *   |        |
 *   |        |
 *   |        |
 *   |        |
 *   |--------|
 *   | GUARDD |
 *   |________|
 */

#ifndef ACH_H
#define ACH_H

#include <signal.h>

/* restict only in C99 */
#ifdef __cplusplus

# define ACH_RESTRICT
#elif  __STDC_VERSION__ < 199901L

#  define ACH_RESTRICT
#else

# define ACH_RESTRICT restrict
#endif

#if (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 5))

#define ACH_DEPRECATED(msg)  __attribute__((__deprecated__(msg)))
#elif (__GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 1))

#define ACH_DEPRECATED(msg)  __attribute__((__deprecated__))
#else

#define ACH_DEPRECATED(msg)
#endif /* __GNUC__ */

/* Determine a default clock */
#ifdef CLOCK_MONOTONIC

#define ACH_DEFAULT_CLOCK CLOCK_MONOTONIC
#elif defined CLOCK_HIGHRES /* Old Solaris lacks CLOCK_MONOTONIC,
                               CLOCK_HIGHRES looks the same */

#define ACH_DEFAULT_CLOCK CLOCK_HIGHRES
#elif defined CLOCK_REALTIME /* Try fallback to CLOCK_REALTIME */

#define ACH_DEFAULT_CLOCK CLOCK_REALTIME
#else
#error No valid CLOCKS defined.  Expecting CLOCK_MONOTONIC.
#endif /* CLOCK_MONOTONIC */

#include "ach/generic.h"

#ifdef __cplusplus
extern "C" {
#endif

    enum ach_map {
        ACH_MAP_DEFAULT = 0,  
        ACH_MAP_ANON = 1,     
        ACH_MAP_USER = 2,     
        ACH_MAP_KERNEL = 3,   
    };

    struct ach_header;

    struct ach_attr {
        union {
            struct{
                union {
                    int map_anon
                    ACH_DEPRECATED("The 'map_anon' field is replaced by the 'map' field of type 'enum ach_map'")
                        ;
                    enum ach_map map;
                };
                struct ach_header *shm;   
                union {
                    uint64_t reserve_bits;           
                    struct {
                        unsigned int lock_source : 1;   
                    };
                };
            };
            uint64_t reserved_size[8]; 
        };
    };

    typedef struct ach_attr ach_attr_t;

    void ach_attr_init( ach_attr_t *attr );

    enum ach_status ACH_WARN_UNUSED
    ach_attr_set_shm( ach_attr_t *attr, struct ach_header *shm );

    enum ach_status
    ach_attr_set_lock_source( ach_attr_t *attr, int lock_source );

    struct ach_create_attr {
        union {
            struct{
                union {
                    int map_anon;            
                    enum ach_map map;        
                };
                struct ach_header *shm;      
                clockid_t clock;             
                union {
                    uint64_t reserve_bits;           
                    struct {
                        unsigned int truncate  : 1;   
                        unsigned int set_clock : 1;   
                    };
                };
            };
            uint64_t reserved[16]; 
        };
    };

    typedef struct ach_create_attr ach_create_attr_t;

    void ach_create_attr_init( ach_create_attr_t *attr );

    enum ach_status ACH_WARN_UNUSED
    ach_create_attr_set_clock( ach_create_attr_t *attr, clockid_t clock );

    enum ach_status ACH_WARN_UNUSED
    ach_create_attr_set_map( ach_create_attr_t *attr, enum ach_map map );

    enum ach_status ACH_WARN_UNUSED
    ach_create_attr_set_truncate( ach_create_attr_t *attr, int truncate );

    enum ach_status ACH_WARN_UNUSED
    ach_create_attr_get_shm( ach_create_attr_t *attr, struct ach_header **shm );

    struct ach_channel_vtab;

    typedef struct ach_channel {
        union {
            struct {
                struct ach_header *shm;                
                size_t len;                            
                int fd;                                
                union {
                    uint64_t seq_num;                  
                    achk_opt_t k_opts;                 
                };
                size_t next_index;                     
                clockid_t clock;                       
                volatile sig_atomic_t cancel;          
                const struct ach_channel_vtab *vtab;   
                int fd_source_lock;                    
            };
            uint64_t reserved[16]; 
        };
    } ach_channel_t;

    enum ach_status ACH_WARN_UNUSED
    ach_channel_fd( const struct ach_channel *channel, int *file_descriptor );

    enum ach_status ACH_WARN_UNUSED
    ach_channel_map( const struct ach_channel *channel, enum ach_map *map );

    enum ach_status ACH_WARN_UNUSED
    ach_channel_clock( const struct ach_channel *channel, clockid_t *clock );

    enum ach_status ACH_WARN_UNUSED
    ach_create( const char *name,
                size_t frame_cnt, size_t frame_size,
                ach_create_attr_t *attr );

    enum ach_status ACH_WARN_UNUSED
    ach_open( ach_channel_t *channel, const char *name,
              ach_attr_t *attr );

    enum ach_status ACH_WARN_UNUSED
    ach_get( ach_channel_t *chan, void *buf, size_t size,
             size_t *frame_size,
             const struct timespec *ACH_RESTRICT abstime,
             int options );

    enum ach_status
    ach_put( ach_channel_t *channel, const void *buf, size_t len );


    enum ach_status ACH_WARN_UNUSED
    ach_flush( ach_channel_t *chan );

    enum ach_status ACH_WARN_UNUSED
    ach_close( ach_channel_t *chan );

    const char *ach_result_to_string(ach_status_t result);


    const char *ach_errstr();

    void ach_dump( struct ach_header *shm);

    enum ach_status
    ach_chmod( ach_channel_t *chan, mode_t mode );

    enum ach_status ACH_WARN_UNUSED
    ach_unlink( const char *name );

    typedef struct ach_cancel_attr {
        union {
            struct {
                unsigned int async_unsafe : 1;
            };
            int64_t reserved[8];
        };
    } ach_cancel_attr_t;

    void
    ach_cancel_attr_init( ach_cancel_attr_t *attr );

    enum ach_status ACH_WARN_UNUSED
    ach_cancel_attr_set_async_unsafe( ach_cancel_attr_t *attr, int asyn_unsafe );

    enum ach_status ACH_WARN_UNUSED
    ach_cancel( ach_channel_t *chan, const ach_cancel_attr_t *attr );

#ifdef __cplusplus
}
#endif

#endif /* ACH_H */