1 /* -*- Mode: C; c-basic-offset:4 ; -*- */
2 /*
3 * Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana
4 * University Research and Technology
5 * Corporation. All rights reserved.
6 * Copyright (c) 2004-2008 The University of Tennessee and The University
7 * of Tennessee Research Foundation. All rights
8 * reserved.
9 * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
10 * University of Stuttgart. All rights reserved.
11 * Copyright (c) 2004-2005 The Regents of the University of California.
12 * All rights reserved.
13 * Copyright (c) 2010 Cisco Systems, Inc. All rights reserved.
14 * $COPYRIGHT$
15 *
16 * Additional copyrights may follow
17 *
18 * $HEADER$
19 */
20 /** @file
21 *
22 */
23
24 #ifndef OPAL_RING_BUFFER_H
25 #define OPAL_RING_BUFFER_H
26
27 #include "opal_config.h"
28
29 #include "opal/threads/threads.h"
30 #include "opal/class/opal_object.h"
31 #include "opal/util/output.h"
32
33 BEGIN_C_DECLS
34
35 /**
36 * dynamic pointer ring
37 */
38 struct opal_ring_buffer_t {
39 /** base class */
40 opal_object_t super;
41 /** synchronization object */
42 opal_mutex_t lock;
43 opal_condition_t cond;
44 bool in_use;
45 /* head/tail indices */
46 int head;
47 int tail;
48 /** size of list, i.e. number of elements in addr */
49 int size;
50 /** pointer to ring */
51 char **addr;
52 };
53 /**
54 * Convenience typedef
55 */
56 typedef struct opal_ring_buffer_t opal_ring_buffer_t;
57 /**
58 * Class declaration
59 */
60 OPAL_DECLSPEC OBJ_CLASS_DECLARATION(opal_ring_buffer_t);
61
62 /**
63 * Initialize the ring buffer, defining its size.
64 *
65 * @param ring Pointer to a ring buffer (IN/OUT)
66 * @param size The number of elements in the ring (IN)
67 *
68 * @return OPAL_SUCCESS if all initializations were succesful. Otherwise,
69 * the error indicate what went wrong in the function.
70 */
71 OPAL_DECLSPEC int opal_ring_buffer_init(opal_ring_buffer_t* ring, int size);
72
73 /**
74 * Push an item onto the ring buffer
75 *
76 * @param ring Pointer to ring (IN)
77 * @param ptr Pointer value (IN)
78 *
79 * @return OPAL_SUCCESS. Returns error if ring cannot take
80 * another entry
81 */
82 OPAL_DECLSPEC void* opal_ring_buffer_push(opal_ring_buffer_t *ring, void *ptr);
83
84
85 /**
86 * Pop an item off of the ring. The oldest entry on the ring will be
87 * returned. If nothing on the ring, NULL is returned.
88 *
89 * @param ring Pointer to ring (IN)
90 *
91 * @return Error code. NULL indicates an error.
92 */
93
94 OPAL_DECLSPEC void* opal_ring_buffer_pop(opal_ring_buffer_t *ring);
95
96 /*
97 * Access an element of the ring, without removing it, indexed
98 * starting at the tail - a value of -1 will return the element
99 * at the head of the ring
100 */
101 OPAL_DECLSPEC void* opal_ring_buffer_poke(opal_ring_buffer_t *ring, int i);
102
103 END_C_DECLS
104
105 #endif /* OPAL_RING_BUFFER_H */