escript/src/DataC.h


/*******************************************************
*
* Copyright (c) 2003-2008 by University of Queensland
* Earth Systems Science Computational Center (ESSCC)
* http://www.uq.edu.au/esscc
*
* Primary Business: Queensland, Australia
* Licensed under the Open Software License version 3.0
* http://www.opensource.org/licenses/osl-3.0.php
*
*******************************************************/


#if !defined  escript_DataC_20040611_H
#define escript_DataC_20040611_H
#include "system_dep.h"

/**
   \brief
   Provide a wrapper around a Data object so Data may be accessed from C.

   Description:
   Provide a wrapper around a Data object so Data may be accessed from C.

*/
struct escriptDataC {
  void* m_dataPtr;
};

typedef struct escriptDataC escriptDataC; 

/**
   \brief
   Return the function space type code.
   \param data Input - C wrapper for Data.
*/
ESCRIPT_DLL_API int getFunctionSpaceType(escriptDataC* data);

/**
   \brief
   sets the int variable _fs_ the function space type of _data_ if the data are not empty.
   \param _fs_ Input/Output - variable to be updated.
   \param _data_ Input - C wrapper for Data.
*/
#define updateFunctionSpaceType(_fs_,_data_) _fs_=(isEmpty(_data_) ? _fs_ : getFunctionSpaceType(_data_))
                                                                                     
/**
   \brief
   is true if the function space type of _data_ is equal to _fs_ or is empty
   \param _fs_ Input - function space type to checked against
   \param _data_ Input - C wrapper for Data.
*/
#define functionSpaceTypeEqual(_fs_,_data_) ( (isEmpty(_data_) || _fs_==getFunctionSpaceType(_data_)) ) ? 1 : 0

/**
   \brief
   Returns the true if the data are empty or data is NULL.
   \param data Input - C wrapper for Data.
*/
ESCRIPT_DLL_API int isEmpty(escriptDataC* data);

/**
   \brief
   Return true if the input shape matches the data point shape for data
   \param data Input - C wrapper for Data.
   \param rank Input - number of dimensions.
   \param dimensions Input - 
*/
ESCRIPT_DLL_API int isDataPointShapeEqual(escriptDataC* data, int rank, int* dimensions);
/**
   \brief
   Return true if the number of data points per sample and the number 
   of samples equal the input values. In the case that data is empty or NULL,
   true is returned.
   \param data Input - C wrapper for Data.
   \param numDataPointsPerSample Input - number of data points per sample
   \param numSamples Input - number of samples
*/
ESCRIPT_DLL_API int numSamplesEqual(escriptDataC* data, int numDataPointsPerSample,
            int numSamples);

/**
   \brief
   Returns the number of data points per sample
   \param data Input - C wrapper for Data.
*/
ESCRIPT_DLL_API int getNumDataPointsPerSample(escriptDataC* data);

/**
   \brief
   Returns the rank of the point data for the data. 
   \param data Input - C wrapper for Data.
*/
ESCRIPT_DLL_API int getDataPointRank(escriptDataC* data);

/**
   \brief
   Returns the value of the i-th component of the shape of the point data.
   \param data Input - C wrapper for Data.
   \param i Input - index of shape component.
*/
ESCRIPT_DLL_API int getDataPointShape(escriptDataC* data,int i);

/**
   \brief
   Return the number of doubles needed for each data point.
   \param data Input - C wrapper for Data.
*/
ESCRIPT_DLL_API int getDataPointSize(escriptDataC* data);

/*
   \brief
   Return the number of doubles stored for the Data object.
   Argument data may be NULL, in which case 0 is returnd.
   \param data Input - C wrapper for Data.

This function has been removed because it does not make sense for LazyData
*/
/*ESCRIPT_DLL_API int getLength(escriptDataC* data);*/

/**
   \brief
   Return true if data can be treated as expanded.
   
   Argument data may be NULL, in which case false is returnd.
   \param data Input - C wrapper for Data.
   \return true if data is expanded or the data is lazy but would resolve to expanded. False otherwise.
*/
ESCRIPT_DLL_API int isExpanded(escriptDataC* data);
/**
   \brief
   Return a pointer to the data for the given sample number.
   if data is empty NULL is returned.
   data may be NULL, in which case NULL is returnd.
  \param data Input - C wrapper for Data.
  \param sampleNo Input - The sample number.
*/
ESCRIPT_DLL_API __const double* getSampleDataRO(escriptDataC* data, int sampleNo, void* buffer);


ESCRIPT_DLL_API double* getSampleDataRW(escriptDataC* data, int sampleNo);


/**
   \brief
   Return a pointer to the data for the given sample number.
   Fast version of getSampledata: does no error checking.
  \param data Input - C wrapper for Data.
  \param sampleNo Input - The sample number.
*/
ESCRIPT_DLL_API double* getSampleDataFast(escriptDataC* data, int sampleNo);


/**
   \brief Create a buffer for use by getSample
   Allocates a DataVector large enough for DataLazy::resolveSample to operate on for the current Data.
   Do not use this buffer for other DataC instances (unless you are sure they will be the same size).
   
   \return A DataVector* if Data is not-NULL and lazy, NULL otherwise.
   \warning This pointer must be deallocated using freeSampleBuffer to avoid cross library memory issues.
   \param data Input - C wrapper for Data.
*/
ESCRIPT_DLL_API void* allocSampleBuffer(escriptDataC* data);

/**
   \brief Free a buffer allocated with allocSampleBuffer.
   \param buffer Input - pointer to the buffer to deallocate.
*/
ESCRIPT_DLL_API void freeSampleBuffer(void* buffer);

#endif
1
2	/*******************************************************
3	*
4	* Copyright (c) 2003-2008 by University of Queensland
5	* Earth Systems Science Computational Center (ESSCC)
6	* http://www.uq.edu.au/esscc
7	*
8	* Primary Business: Queensland, Australia
9	* Licensed under the Open Software License version 3.0
10	* http://www.opensource.org/licenses/osl-3.0.php
11	*
12	*******************************************************/
13
14
15	#if !defined escript_DataC_20040611_H
16	#define escript_DataC_20040611_H
17	#include "system_dep.h"
18
19	/**
20	\brief
21	Provide a wrapper around a Data object so Data may be accessed from C.
22
23	Description:
24	Provide a wrapper around a Data object so Data may be accessed from C.
25
26	*/
27	struct escriptDataC {
28	void* m_dataPtr;
29	};
30
31	typedef struct escriptDataC escriptDataC;
32
33	/**
34	\brief
35	Return the function space type code.
36	\param data Input - C wrapper for Data.
37	*/
38	ESCRIPT_DLL_API int getFunctionSpaceType(escriptDataC* data);
39
40	/**
41	\brief
42	sets the int variable _fs_ the function space type of _data_ if the data are not empty.
43	\param _fs_ Input/Output - variable to be updated.
44	\param _data_ Input - C wrapper for Data.
45	*/
46	#define updateFunctionSpaceType(_fs_,_data_) _fs_=(isEmpty(_data_) ? _fs_ : getFunctionSpaceType(_data_))
47
48	/**
49	\brief
50	is true if the function space type of _data_ is equal to _fs_ or is empty
51	\param _fs_ Input - function space type to checked against
52	\param _data_ Input - C wrapper for Data.
53	*/
54	#define functionSpaceTypeEqual(_fs_,_data_) ( (isEmpty(_data_) \|\| _fs_==getFunctionSpaceType(_data_)) ) ? 1 : 0
55
56	/**
57	\brief
58	Returns the true if the data are empty or data is NULL.
59	\param data Input - C wrapper for Data.
60	*/
61	ESCRIPT_DLL_API int isEmpty(escriptDataC* data);
62
63	/**
64	\brief
65	Return true if the input shape matches the data point shape for data
66	\param data Input - C wrapper for Data.
67	\param rank Input - number of dimensions.
68	\param dimensions Input -
69	*/
70	ESCRIPT_DLL_API int isDataPointShapeEqual(escriptDataC* data, int rank, int* dimensions);
71	/**
72	\brief
73	Return true if the number of data points per sample and the number
74	of samples equal the input values. In the case that data is empty or NULL,
75	true is returned.
76	\param data Input - C wrapper for Data.
77	\param numDataPointsPerSample Input - number of data points per sample
78	\param numSamples Input - number of samples
79	*/
80	ESCRIPT_DLL_API int numSamplesEqual(escriptDataC* data, int numDataPointsPerSample,
81	int numSamples);
82
83	/**
84	\brief
85	Returns the number of data points per sample
86	\param data Input - C wrapper for Data.
87	*/
88	ESCRIPT_DLL_API int getNumDataPointsPerSample(escriptDataC* data);
89
90	/**
91	\brief
92	Returns the rank of the point data for the data.
93	\param data Input - C wrapper for Data.
94	*/
95	ESCRIPT_DLL_API int getDataPointRank(escriptDataC* data);
96
97	/**
98	\brief
99	Returns the value of the i-th component of the shape of the point data.
100	\param data Input - C wrapper for Data.
101	\param i Input - index of shape component.
102	*/
103	ESCRIPT_DLL_API int getDataPointShape(escriptDataC* data,int i);
104
105	/**
106	\brief
107	Return the number of doubles needed for each data point.
108	\param data Input - C wrapper for Data.
109	*/
110	ESCRIPT_DLL_API int getDataPointSize(escriptDataC* data);
111
112	/*
113	\brief
114	Return the number of doubles stored for the Data object.
115	Argument data may be NULL, in which case 0 is returnd.
116	\param data Input - C wrapper for Data.
117
118	This function has been removed because it does not make sense for LazyData
119	*/
120	/ESCRIPT_DLL_API int getLength(escriptDataC data);*/
121
122	/**
123	\brief
124	Return true if data can be treated as expanded.
125
126	Argument data may be NULL, in which case false is returnd.
127	\param data Input - C wrapper for Data.
128	\return true if data is expanded or the data is lazy but would resolve to expanded. False otherwise.
129	*/
130	ESCRIPT_DLL_API int isExpanded(escriptDataC* data);
131	/**
132	\brief
133	Return a pointer to the data for the given sample number.
134	if data is empty NULL is returned.
135	data may be NULL, in which case NULL is returnd.
136	\param data Input - C wrapper for Data.
137	\param sampleNo Input - The sample number.
138	*/
139	ESCRIPT_DLL_API __const double* getSampleDataRO(escriptDataC* data, int sampleNo, void* buffer);
140
141
142	ESCRIPT_DLL_API double* getSampleDataRW(escriptDataC* data, int sampleNo);
143
144
145	/**
146	\brief
147	Return a pointer to the data for the given sample number.
148	Fast version of getSampledata: does no error checking.
149	\param data Input - C wrapper for Data.
150	\param sampleNo Input - The sample number.
151	*/
152	ESCRIPT_DLL_API double* getSampleDataFast(escriptDataC* data, int sampleNo);
153
154
155	/**
156	\brief Create a buffer for use by getSample
157	Allocates a DataVector large enough for DataLazy::resolveSample to operate on for the current Data.
158	Do not use this buffer for other DataC instances (unless you are sure they will be the same size).
159
160	\return A DataVector* if Data is not-NULL and lazy, NULL otherwise.
161	\warning This pointer must be deallocated using freeSampleBuffer to avoid cross library memory issues.
162	\param data Input - C wrapper for Data.
163	*/
164	ESCRIPT_DLL_API void* allocSampleBuffer(escriptDataC* data);
165
166	/**
167	\brief Free a buffer allocated with allocSampleBuffer.
168	\param buffer Input - pointer to the buffer to deallocate.
169	*/
170	ESCRIPT_DLL_API void freeSampleBuffer(void* buffer);
171
172	#endif
Name	Value
svn:eol-style	native
svn:keywords	Author Date Id Revision