[waffle] [PATCH 1/3] waffle: add public func waffle_teardown()
Emil Velikov
emil.l.velikov at gmail.com
Thu Jan 15 07:21:57 PST 2015
It will be used to teardown the global state, make valgrind happy and catch
(point out) a bug or two in the GL/EGL/etc implementations.
See the man page for more details.
Signed-off-by: Emil Velikov <emil.l.velikov at gmail.com>
---
include/waffle/waffle.h | 5 ++
man/common/author-emil.velikov.xml | 8 +++
man/html.cmake | 2 +
man/manpages.cmake | 2 +
man/waffle_init.3.xml | 3 +-
man/waffle_teardown.3.xml | 115 +++++++++++++++++++++++++++++++++++++
src/waffle/api/api_priv.h | 6 +-
src/waffle/api/waffle_init.c | 21 +++++++
src/waffle/waffle.def.in | 1 +
9 files changed, 159 insertions(+), 4 deletions(-)
create mode 100644 man/common/author-emil.velikov.xml
create mode 100644 man/waffle_teardown.3.xml
diff --git a/include/waffle/waffle.h b/include/waffle/waffle.h
index e04b23f..6d200c2 100644
--- a/include/waffle/waffle.h
+++ b/include/waffle/waffle.h
@@ -160,6 +160,11 @@ waffle_enum_to_string(int32_t e);
bool
waffle_init(const int32_t *attrib_list);
+#if WAFFLE_API_VERSION >= 0x0106
+bool
+waffle_teardown(void);
+#endif
+
bool
waffle_make_current(struct waffle_display *dpy,
struct waffle_window *window,
diff --git a/man/common/author-emil.velikov.xml b/man/common/author-emil.velikov.xml
new file mode 100644
index 0000000..382a947
--- /dev/null
+++ b/man/common/author-emil.velikov.xml
@@ -0,0 +1,8 @@
+<?xml version='1.0'?>
+
+<author>
+ <firstname>Emil</firstname>
+ <surname>Velikov</surname>
+ <email>emil.l.velikov at gmail.com</email>
+ <contrib>Contributor</contrib>
+</author>
diff --git a/man/html.cmake b/man/html.cmake
index 59e0490..e783373 100644
--- a/man/html.cmake
+++ b/man/html.cmake
@@ -43,6 +43,7 @@ set(html_outputs
${html_out_dir}/waffle_is_extension_in_string.3.html
${html_out_dir}/waffle_make_current.3.html
${html_out_dir}/waffle_native.3.html
+ ${html_out_dir}/waffle_teardown.3.html
${html_out_dir}/waffle_wayland.3.html
${html_out_dir}/waffle_window.3.html
${html_out_dir}/waffle_x11_egl.3.html
@@ -81,6 +82,7 @@ waffle_add_html(3 waffle_init)
waffle_add_html(3 waffle_is_extension_in_string)
waffle_add_html(3 waffle_make_current)
waffle_add_html(3 waffle_native)
+waffle_add_html(3 waffle_teardown)
waffle_add_html(3 waffle_wayland)
waffle_add_html(3 waffle_window)
waffle_add_html(3 waffle_x11_egl)
diff --git a/man/manpages.cmake b/man/manpages.cmake
index b8ededa..b0c20b3 100644
--- a/man/manpages.cmake
+++ b/man/manpages.cmake
@@ -45,6 +45,7 @@ set(man_outputs
${man_out_dir}/man3/waffle_is_extension_in_string.3
${man_out_dir}/man3/waffle_make_current.3
${man_out_dir}/man3/waffle_native.3
+ ${man_out_dir}/man3/waffle_teardown.3
${man_out_dir}/man3/waffle_wayland.3
${man_out_dir}/man3/waffle_window.3
${man_out_dir}/man3/waffle_x11_egl.3
@@ -81,6 +82,7 @@ waffle_add_manpage(3 waffle_init)
waffle_add_manpage(3 waffle_is_extension_in_string)
waffle_add_manpage(3 waffle_make_current)
waffle_add_manpage(3 waffle_native)
+waffle_add_manpage(3 waffle_teardown)
waffle_add_manpage(3 waffle_wayland)
waffle_add_manpage(3 waffle_window)
waffle_add_manpage(3 waffle_x11_egl)
diff --git a/man/waffle_init.3.xml b/man/waffle_init.3.xml
index a22723d..4dd77d5 100644
--- a/man/waffle_init.3.xml
+++ b/man/waffle_init.3.xml
@@ -60,7 +60,8 @@
<para>
If a call to <function>waffle_init()</function> fails, no global state is initialized and the caller may safely
attempt to call <function>waffle_init()</function> again. If waffle has already been initialized by a successful
- call to <function>waffle_init()</function>, then calling <function>waffle_init()</function> again emits the error
+ call to <function>waffle_init()</function> one has to call <function>waffle_teardown()</function> to clear the
+ global state. Otherwise calling <function>waffle_init()</function> again emits the error
<errorcode>WAFFLE_ERROR_ALREADY_INITIALIZED</errorcode>.
</para>
diff --git a/man/waffle_teardown.3.xml b/man/waffle_teardown.3.xml
new file mode 100644
index 0000000..69b18e9
--- /dev/null
+++ b/man/waffle_teardown.3.xml
@@ -0,0 +1,115 @@
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+ Copyright Intel 2015
+
+ This manual page is licensed under the Creative Commons Attribution-ShareAlike 3.0 United States License (CC BY-SA 3.0
+ US). To view a copy of this license, visit http://creativecommons.org.license/by-sa/3.0/us.
+-->
+
+<refentry
+ id="waffle_teardown"
+ xmlns:xi="http://www.w3.org/2001/XInclude">
+
+ <!-- See http://www.docbook.org/tdg/en/html/refentry.html. -->
+
+ <refmeta>
+ <refentrytitle>waffle_teardown</refentrytitle>
+ <manvolnum>3</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>waffle_teardown</refname>
+ <refpurpose>Teardown waffle's per-process global state</refpurpose>
+ </refnamediv>
+
+ <refentryinfo>
+ <title>Waffle Manual</title>
+ <productname>waffle</productname>
+ <xi:include href="common/author-emil.velikov.xml"/>
+ <xi:include href="common/copyright.xml"/>
+ <xi:include href="common/legalnotice.xml"/>
+ </refentryinfo>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcsynopsisinfo><![CDATA[#include <waffle.h>]]></funcsynopsisinfo>
+ <funcprototype>
+ <funcdef>bool <function>waffle_teardown</function></funcdef>
+ <void/>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <term><function>waffle_teardown()</function></term>
+ <listitem>
+ <para>
+ Feature test macro: <code>WAFFLE_API_VERSION >= 0x0106</code>.
+ (See <citerefentry><refentrytitle>waffle_feature_test_macros</refentrytitle><manvolnum>7</manvolnum></citerefentry>).
+ </para>
+ <para>
+ Tears down the per-process global state of the waffle library.
+ </para>
+ <para>
+ А call to <function>waffle_teardown()</function> can fail. In the case it does the caller is advised
+ to use <function>waffle_error_get_info</function>, <function>waffle_error_get_code</function>
+ and/or <function>waffle_error_to_string</function> to retrieve the error.
+
+ In case of an error that differs from <errorcode>WAFFLE_ERROR_NOT_INITIALIZED</errorcode> the caller
+ should not use the Waffle API as the global state is likely to be in an undetermined/corrupt.
+
+ In the case of <errorcode>WAFFLE_ERROR_NOT_INITIALIZED</errorcode> one should call
+ <function>waffle_init()</function> prior to reusing Waffle.
+ </para>
+ </listitem>
+ </refsect1>
+
+ <refsect1>
+ <title>Return Value</title>
+ <xi:include href="common/return-value.xml"/>
+ </refsect1>
+
+ <refsect1>
+ <title>Errors</title>
+
+ <xi:include href="common/error-codes.xml"/>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><errorcode>WAFFLE_ERROR_NOT_INITIALIZED</errorcode></term>
+ <listitem>
+ <para>
+ Waffle has not been initialized with a successfull call to <function>waffle_init()</function>
+ since the last call to <function>waffle_teardown()</function> or the start of the program.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </refsect1>
+
+ <xi:include href="common/issues.xml"/>
+
+ <refsect1>
+ <title>See Also</title>
+
+ <para>
+ <simplelist>
+ <member><citerefentry><refentrytitle>waffle_init</refentrytitle><manvolnum>3</manvolnum></citerefentry>,</member>
+ <member><citerefentry><refentrytitle>waffle</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</member>
+ </simplelist>
+ </para>
+ </refsect1>
+
+</refentry>
+
+<!--
+vim:tw=120 et ts=2 sw=2:
+-->
diff --git a/src/waffle/api/api_priv.h b/src/waffle/api/api_priv.h
index 51cf53c..0e17326 100644
--- a/src/waffle/api/api_priv.h
+++ b/src/waffle/api/api_priv.h
@@ -50,10 +50,10 @@
struct api_object;
struct wcore_platform;
-/// @brief Managed by waffle_init().
+/// @brief Managed by waffle_init() and waffle_teardown().
///
-/// This is null if and only if waffle has not been initialized with
-/// waffle_init().
+/// This is null if waffle has not been initialized with waffle_init() or
+/// it has been thrown down with waffle_teardown().
extern struct wcore_platform *api_platform;
/// @brief Used to validate most API entry points.
diff --git a/src/waffle/api/waffle_init.c b/src/waffle/api/waffle_init.c
index ebc6cd5..d5b7224 100644
--- a/src/waffle/api/waffle_init.c
+++ b/src/waffle/api/waffle_init.c
@@ -193,3 +193,24 @@ waffle_init(const int32_t *attrib_list)
return true;
}
+
+WAFFLE_API bool
+waffle_teardown(void)
+{
+ bool ok = true;
+
+ // XXX: Do we really want to reset the error info ?
+ wcore_error_reset();
+
+ if (!api_platform) {
+ wcore_error(WAFFLE_ERROR_NOT_INITIALIZED);
+ return false;
+ }
+
+ ok &= api_platform->vtbl->destroy(api_platform);
+ if (!ok)
+ return false;
+
+ api_platform = NULL;
+ return true;
+}
diff --git a/src/waffle/waffle.def.in b/src/waffle/waffle.def.in
index db8464f..7912103 100644
--- a/src/waffle/waffle.def.in
+++ b/src/waffle/waffle.def.in
@@ -6,6 +6,7 @@ EXPORTS
waffle_error_to_string
waffle_enum_to_string
waffle_init
+ waffle_teardown
waffle_make_current
waffle_get_proc_address
waffle_is_extension_in_string
--
2.1.3
More information about the waffle
mailing list