src/class/pmix_ring_buffer.h

0001 /* -*- Mode: C; c-basic-offset:4 ; -*- */
0002 /*
0003  * Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana
0004  *                         University Research and Technology
0005  *                         Corporation.  All rights reserved.
0006  * Copyright (c) 2004-2008 The University of Tennessee and The University
0007  *                         of Tennessee Research Foundation.  All rights
0008  *                         reserved.
0009  * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
0010  *                         University of Stuttgart.  All rights reserved.
0011  * Copyright (c) 2004-2005 The Regents of the University of California.
0012  *                         All rights reserved.
0013  * Copyright (c) 2010      Cisco Systems, Inc. All rights reserved.
0014  * Copyright (c) 2016-2020 Intel, Inc.  All rights reserved.
0015  * Copyright (c) 2021-2022 Nanook Consulting.  All rights reserved.
0016  * $COPYRIGHT$
0017  *
0018  * Additional copyrights may follow
0019  *
0020  * $HEADER$
0021  */
0022 /** @file
0023  *
0024  */
0025
0026 #ifndef PMIX_RING_BUFFER_H
0027 #define PMIX_RING_BUFFER_H
0028
0029 #include "src/include/pmix_config.h"
0030
0031 #include "src/class/pmix_object.h"
0032 #include "src/util/pmix_output.h"
0033
0034 BEGIN_C_DECLS
0035
0036 /**
0037  * dynamic pointer ring
0038  */
0039 struct pmix_ring_buffer_t {
0040     /** base class */
0041     pmix_object_t super;
0042     /* head/tail indices */
0043     int head;
0044     int tail;
0045     /** size of list, i.e. number of elements in addr */
0046     int size;
0047     /** pointer to ring */
0048     char **addr;
0049 };
0050 /**
0051  * Convenience typedef
0052  */
0053 typedef struct pmix_ring_buffer_t pmix_ring_buffer_t;
0054 /**
0055  * Class declaration
0056  */
0057 PMIX_CLASS_DECLARATION(pmix_ring_buffer_t);
0058
0059 /**
0060  * Initialize the ring buffer, defining its size.
0061  *
0062  * @param ring Pointer to a ring buffer (IN/OUT)
0063  * @param size The number of elements in the ring (IN)
0064  *
0065  * @return PMIX_SUCCESS if all initializations were successful. Otherwise,
0066  *  the error indicate what went wrong in the function.
0067  */
0068 PMIX_EXPORT int pmix_ring_buffer_init(pmix_ring_buffer_t *ring, int size);
0069
0070 /**
0071  * Push an item onto the ring buffer, displacing the oldest
0072  * item on the ring if the ring is full
0073  *
0074  * @param ring Pointer to ring (IN)
0075  * @param ptr Pointer value (IN)
0076  *
0077  * @return Pointer to displaced item, NULL if ring
0078  *         is not yet full
0079  */
0080 PMIX_EXPORT void *pmix_ring_buffer_push(pmix_ring_buffer_t *ring, void *ptr);
0081
0082 /**
0083  * Pop an item off of the ring. The oldest entry on the ring will be
0084  * returned. If nothing on the ring, NULL is returned.
0085  *
0086  * @param ring          Pointer to ring (IN)
0087  *
0088  * @return Error code.  NULL indicates an error.
0089  */
0090
0091 PMIX_EXPORT void *pmix_ring_buffer_pop(pmix_ring_buffer_t *ring);
0092
0093 /*
0094  * Access an element of the ring, without removing it, indexed
0095  * starting at the tail - a value of -1 will return the element
0096  * at the head of the ring
0097  */
0098 PMIX_EXPORT void *pmix_ring_buffer_poke(pmix_ring_buffer_t *ring, int i);
0099
0100 END_C_DECLS
0101
0102 #endif /* PMIX_RING_BUFFER_H */