xref: /freebsd/sys/dev/isci/scil/sci_base_observer.h (revision 7fdf597e96a02165cfe22ff357b857d5fa15ed8a)
1 /*-
2  * SPDX-License-Identifier: BSD-2-Clause OR GPL-2.0
3  *
4  * This file is provided under a dual BSD/GPLv2 license.  When using or
5  * redistributing this file, you may do so under either license.
6  *
7  * GPL LICENSE SUMMARY
8  *
9  * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved.
10  *
11  * This program is free software; you can redistribute it and/or modify
12  * it under the terms of version 2 of the GNU General Public License as
13  * published by the Free Software Foundation.
14  *
15  * This program is distributed in the hope that it will be useful, but
16  * WITHOUT ANY WARRANTY; without even the implied warranty of
17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
18  * General Public License for more details.
19  *
20  * You should have received a copy of the GNU General Public License
21  * along with this program; if not, write to the Free Software
22  * Foundation, Inc., 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA.
23  * The full GNU General Public License is included in this distribution
24  * in the file called LICENSE.GPL.
25  *
26  * BSD LICENSE
27  *
28  * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved.
29  * All rights reserved.
30  *
31  * Redistribution and use in source and binary forms, with or without
32  * modification, are permitted provided that the following conditions
33  * are met:
34  *
35  *   * Redistributions of source code must retain the above copyright
36  *     notice, this list of conditions and the following disclaimer.
37  *   * Redistributions in binary form must reproduce the above copyright
38  *     notice, this list of conditions and the following disclaimer in
39  *     the documentation and/or other materials provided with the
40  *     distribution.
41  *
42  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
43  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
44  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
45  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
46  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
47  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
48  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
49  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
50  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
51  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
52  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
53  */
54 #ifndef _SCI_BASE_OBSERVER_H_
55 #define _SCI_BASE_OBSERVER_H_
56 
57 /**
58  * @file
59  *
60  * @brief This file contains all of the structures, constants, and methods
61  *        common to all base observer object definitions.
62  */
63 
64 #ifdef __cplusplus
65 extern "C" {
66 #endif // __cplusplus
67 
68 #if defined(SCI_LOGGING)
69 
70 struct SCI_BASE_OBSERVER;
71 struct SCI_BASE_SUBJECT;
72 
73 /**
74  * @typedef SCI_BASE_OBSERVER_UPDATE_T
75  *
76  * @brief This type definition defines the format for the update method
77  *        that is invoked for all observers participating in the observer
78  *        design pattern.
79  */
80 typedef void (*SCI_BASE_OBSERVER_UPDATE_T)(
81    struct SCI_BASE_OBSERVER *this_observer,
82    struct SCI_BASE_SUBJECT  *the_subject
83 );
84 
85 /**
86  * @struct SCI_BASE_OBSERVER
87  *
88  * @brief This structure defines the fields necessary for an object that
89  *        intends to participate as an observer.
90  */
91 typedef struct SCI_BASE_OBSERVER
92 {
93    /**
94     * This filed points to the next observer if there is one
95     */
96     struct SCI_BASE_OBSERVER *next;
97 
98    /**
99     * This field defines the function pointer that is invoked in order to
100     * notify the observer of a change in the subject (i.e. observed object).
101     */
102    SCI_BASE_OBSERVER_UPDATE_T update;
103 
104 } SCI_BASE_OBSERVER_T;
105 
106 /**
107  * @brief This method is the basic constructor for the observer
108  *
109  * @param[in] this_observer This parameter specifies the observer to
110  *            be constructed.
111  * @param[in] update This parameter specifies the update method to be
112  *            invoked for this observer.
113  *
114  * @return none
115  */
116 void sci_base_observer_construct(
117    struct SCI_BASE_OBSERVER   *this_observer,
118    SCI_BASE_OBSERVER_UPDATE_T  update
119 );
120 
121 /**
122  * @brief This method performs the actions of construction and attaches to the
123  *        subject.
124  *
125  * @pre The the_subject to be observed must be constructed before this call.
126  *
127  * @param[in] this_observer This parameter specifies the observer to construct
128  *       an attach to the subject.
129  * @param[in] update This parameter is the update function that is passed to
130  *       the constructor.
131  * @param[in] the_subject This parameter specifies the subject to observe.
132  */
133 void sci_base_observer_initialize(
134    struct SCI_BASE_OBSERVER   *this_observer,
135    SCI_BASE_OBSERVER_UPDATE_T  update,
136    struct SCI_BASE_SUBJECT    *the_subject
137 );
138 
139 /**
140  * @brief This method will call the observers update function
141  *
142  * @param[in] this_observer This parameter specifies the observer to be
143  *            notified.
144  * @param[in] the_subject This parameter indicates the subject for which
145  *            the update call is occurring.
146  *
147  * @return none
148  */
149 void sci_base_observer_update(
150    struct SCI_BASE_OBSERVER *this_observer,
151    struct SCI_BASE_SUBJECT  *the_subject
152 );
153 
154 #else // defined(SCI_LOGGING)
155 
156 typedef U8 SCI_BASE_OBSERVER_T;
157 #define sci_base_observer_construct
158 #define sci_base_observer_initialize
159 #define sci_base_observer_update
160 
161 #endif // defined(SCI_LOGGING)
162 
163 #ifdef __cplusplus
164 }
165 #endif // __cplusplus
166 
167 #endif // _SCI_BASE_OBSERVER_H_
168