0.0.11 release

pleiszenburg · Apr 10, 2018 · 2a690a6 · 2a690a6
2 parents 24451a8 + fd96022
commit 2a690a6
Show file tree

Hide file tree

Showing 37 changed files with 1,805 additions and 460 deletions.
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -1,6 +1,21 @@
 Changes
 =======
 
+0.0.11 (2018-04-10)
+-------------------
+
+Caution: This release features a significant re-implementation (with additional, new functionality) of the memory synchronization protocol, ``memsync``.
+As a part of it, overcoming old limitations, its syntax changed - effectively breaking backwards compatibility in almost call cases.
+Please check the updated documentation, examples and tests for details.
+
+* FEATURE: Memsync can handle pointers to memory, which was allocated by a DLL, see issue #37.
+* FEATURE: Memsync can target return values or elements within, see issue #40.
+* FEATURE: Memsync can be applied to callback functions, see issue #41 - support at this stage is largely untested.
+* Memsync became more memory efficient and slightly faster.
+* Memsync syntax for custom length functions has been changed. ``_f`` becomes obsolete. ``f`` expects a string, which can be parsed into a function.
+* Memsync syntax for NULL-terminated strings (both ``c_char`` and ``c_wchar``, i.e. Unicode, buffers) has been simplified: ``n`` must be set to ``True`` indicating a NULL-terminated string. ``l`` becomes optional in this context.
+* Memsync syntax for Unicode strings (buffers) has been simplified: ``w`` must be set to ``True`` instead of the length of ``ctypes.c_wchar``.
+
 0.0.10 (2018-03-23)
 -------------------
 
@@ -11,6 +26,8 @@ Changes
 0.0.9 (2018-03-21)
 ------------------
 
+Caution: This release introduces a change in configuration parameter naming, breaking backwards compatibility in rare cases.
+
 * FIX: Arch "win64" was broken because of wrong download URL for embedded CPython for win64/amd64, see issue #27.
 * FIX: Function pointers in struct types were not handled, see issue #28.
 * FIX: Memsync directives pointing to elements within structs were not handled properly, see issue #29.

diff --git a/HOWTORELEASE.rst b/HOWTORELEASE.rst
@@ -3,19 +3,21 @@ How to release zugbruecke
 
 #. Merge all relevant changes into branch ``develop`` - this is where development and pre-release testing happens.
 
-#. In branch ``develop``, run tests and examples ...
+#. In branch ``develop``, run tests and examples and check that the documentation builds without errors.
 
-#. In branch ``develop``, adjust package version in ``setup.py`` by changing the ``version`` string.
+	.. code:: bash
+
+		make test
 
-#. In branch ``develop``, add changes to ``CHANGES.rst``.
+#. In branch ``develop``, add missing changes to ``CHANGES.rst`` and commit.
 
 #. Push branch ``develop`` to GitHub.
 
 #. Wait for feedback from Travis CI.
 
 #. Change to branch ``master``.
 
-#. Merge branch ``develop`` into branch ``master``.
+#. Merge branch ``develop`` into branch ``master`` (comment ``"%s release"  % version``).
 
 #. Push branch ``master`` to GitHub.
 
@@ -48,3 +50,13 @@ How to release zugbruecke
 	.. code:: bash
 
 		make upload
+
+#. Change to branch ``develop``.
+
+#. In branch ``develop``, bump the package version in ``setup.py`` by changing the ``version`` string.
+
+#. In ``CHANGES.rst``, indicate that a new development cycle has started.
+
+#. Commit to branch ``develop``.
+
+#. Push branch ``develop`` to GitHub.
diff --git a/README.rst b/README.rst
@@ -92,15 +92,13 @@ Prerequisites
 Installation
 ============
 
-+--------------------+--------------------------------------------------------------------------+
-| master / release   + .. code:: bash                                                           +
-|                    +                                                                          +
-| |build_master|     +  pip install zugbruecke                                                  +
-+--------------------+--------------------------------------------------------------------------+
-| development branch + .. code:: bash                                                           +
-|                    +                                                                          +
-| |build_develop|    +  pip install git+https://github.com/pleiszenburg/zugbruecke.git@develop  +
-+--------------------+--------------------------------------------------------------------------+
++--------------------+--------------------+-----------------------------------------------------------------------------+--------------------+
+| *branch*           + *status*           + *installation*                                                              + *documentation*    +
++--------------------+--------------------+-----------------------------------------------------------------------------+--------------------+
+| master (release)   + |build_master|     + ``pip install zugbruecke``                                                  + |docs_master|      +
++--------------------+--------------------+-----------------------------------------------------------------------------+--------------------+
+| develop            + |build_develop|    + ``pip install git+https://github.com/pleiszenburg/zugbruecke.git@develop``  + |docs_develop|     +
++--------------------+--------------------+-----------------------------------------------------------------------------+--------------------+
 
 Examples
 ========
@@ -109,21 +107,30 @@ Start an interactive Python session under Unix and try the following:
 
 .. code:: python
 
-	from zugbruecke import cdll, c_double
-	dll_pow = cdll.msvcrt.pow
-	dll_pow.argtypes = (c_double, c_double)
-	dll_pow.restype = c_double
+	import zugbruecke as ctypes
+	dll_pow = ctypes.cdll.msvcrt.pow
+	dll_pow.argtypes = (ctypes.c_double, ctypes.c_double)
+	dll_pow.restype = ctypes.c_double
 	print('You should expect "1024.0" to show up here: "%.1f".' % dll_pow(2.0, 10.0))
 
-You have just witnessed ``msvcrt.dll`` in action on Unix. Interested in more?
-Check the `examples`_ in zugbruecke's documentation or read `ctypes' documentation`_.
+You have just witnessed ``msvcrt.dll``, Microsoft's C standard library (or Wine's implementation of it), in action on Unix.
+
+**Interested in more?**
+
+- Check the `examples`_ in zugbruecke's documentation,
+- Read `ctypes' documentation`_,
+- Beyond ctypes syntax, learn about `memory synchronization`_ with the ``memsync`` routine attribute [or]
+- Have a look at zugbruecke's `test suite`_ showcasing its entire range of capabilities.
 
 A lot of code, which was written with ``ctypes``' ``cdll``, ``windll`` or ``oledll``
 in mind and which runs under Windows, should run just fine with zugbruecke
 on Unix (assuming it does not use Windows features not supported by Wine).
+For more complex calls, `memory synchronization`_ is potentially necessary.
 
 .. _examples: http://zugbruecke.readthedocs.io/en/stable/examples.html
 .. _ctypes' documentation: https://docs.python.org/3/library/ctypes.html
+.. _test suite: https://github.com/pleiszenburg/zugbruecke/tree/master/tests
+.. _memory synchronization: http://zugbruecke.readthedocs.io/en/latest/memsync.html
 
 Speed
 =====
@@ -155,7 +162,7 @@ Bugs & issues
 
 - Report bugs in zugbruecke here: `GitHub issue tracker`_
 - Report bugs in ctypes here: `Python tracker`_
-- Report bug in Wine here: `WineHQ Bug Tracking System`_
+- Report bugs in Wine here: `WineHQ Bug Tracking System`_
 
 Make sure you have read the chapter on `bugs`_ in zugbruecke's documentation.
 
@@ -172,22 +179,24 @@ Miscellaneous
   - at `Read the Docs`_
   - at `zugbruecke repository`_
 
-- `License`_ (**LGPL v2.1**)
+- `Authors`_
+- `Change log (current)`_ (changes in development branch since last release)
+- `Change log (past)`_ (release history)
 - `Contributing`_ (**Contributions are highly welcomed!**)
 - `FAQ`_
-- `Authors`_
-- `Changes`_
-- `Missing features`_ (for full ctypes compatibility)
+- `License`_ (**LGPL v2.1**)
 - `Long-term ideas`_
+- `Missing features`_ (for full ctypes compatibility)
 - `Upstream issues`_ (relevant bugs in dependencies)
 
 .. _Read the Docs: http://zugbruecke.readthedocs.io/en/latest/
-.. _zugbruecke repository: docs/index.rst
+.. _zugbruecke repository: https://github.com/pleiszenburg/zugbruecke/blob/master/docs/index.rst
 .. _License: https://github.com/pleiszenburg/zugbruecke/blob/master/LICENSE
 .. _Contributing: https://github.com/pleiszenburg/zugbruecke/blob/master/CONTRIBUTING.rst
 .. _FAQ: http://zugbruecke.readthedocs.io/en/stable/faq.html
 .. _Authors: https://github.com/pleiszenburg/zugbruecke/blob/master/AUTHORS.rst
-.. _Changes: https://github.com/pleiszenburg/zugbruecke/blob/master/CHANGES.rst
+.. _Change log (past): https://github.com/pleiszenburg/zugbruecke/blob/master/CHANGES.rst
+.. _Change log (current): https://github.com/pleiszenburg/zugbruecke/blob/develop/CHANGES.rst
 .. _Missing features: https://github.com/pleiszenburg/zugbruecke/issues?q=is%3Aissue+is%3Aopen+label%3A%22missing+ctypes+feature%22
 .. _Long-term ideas: https://github.com/pleiszenburg/zugbruecke/milestone/2
 .. _Upstream issues: https://github.com/pleiszenburg/zugbruecke/issues?q=is%3Aissue+is%3Aopen+label%3Aupstream

diff --git a/demo_dll/demo_dll.c b/demo_dll/demo_dll.c
@@ -259,6 +259,31 @@ vector3d __stdcall DEMODLL *vector3d_add(
 }
 
 
+vector3d __stdcall DEMODLL *vector3d_add_array(
+	vector3d *v,
+	int16_t len
+	)
+{
+
+	int16_t i;
+
+	vector3d *v_out = malloc(sizeof(vector3d));
+	v_out->x = 0;
+	v_out->y = 0;
+	v_out->z = 0;
+
+	for(i = 0; i < len; i++)
+	{
+		v_out->x += v[i].x;
+		v_out->y += v[i].y;
+		v_out->z += v[i].z;
+	}
+
+	return v_out;
+
+}
+
+
 int16_t __stdcall DEMODLL sqrt_int(
 	int16_t a
 	)
@@ -317,6 +342,53 @@ int16_t __stdcall DEMODLL get_const_int(void)
 }
 
 
+void __stdcall DEMODLL square_int_array(
+	int16_t *in_array,
+	void *out_array,
+	int16_t len
+	)
+{
+	int i;
+	int16_t **out_array_p = out_array;
+	*out_array_p = malloc(sizeof(int16_t) * len);
+	for(i = 0; i < len; i++)
+	{
+		(*out_array_p)[i] = in_array[i] * in_array[i];
+	}
+}
+
+
+void __stdcall DEMODLL square_int_array_with_struct(
+	int_array_data *in_array,
+	int_array_data *out_array
+	)
+{
+	int i;
+	out_array->len = in_array->len;
+	out_array->data = malloc(sizeof(int16_t) * out_array->len);
+	for(i = 0; i < in_array->len; i++)
+	{
+		out_array->data[i] = in_array->data[i] * in_array->data[i];
+	}
+}
+
+
+int_array_data __stdcall DEMODLL *fibonacci_sequence_a(
+	int16_t len
+	)
+{
+	int16_t i;
+	int_array_data *out_data = malloc(sizeof(int_array_data));
+	out_data->len = len;
+	out_data->data = malloc(sizeof(int16_t) * out_data->len);
+	for(i = 0; i < len; i++){
+		if(i == 0 || i == 1) { out_data->data[i] = 1; continue; }
+		out_data->data[i] = out_data->data[i - 1] + out_data->data[i - 2];
+	}
+	return out_data;
+}
+
+
 void __stdcall DEMODLL replace_letter_in_null_terminated_string_a(
 	char *in_string,
 	char old_letter,
@@ -377,6 +449,38 @@ void __stdcall DEMODLL replace_letter_in_null_terminated_string_unicode_b(
 }
 
 
+void __stdcall DEMODLL tag_string_a(
+	char *in_string,
+	void *out_string
+	)
+{
+	int str_len = strlen(in_string);
+
+	char **out_string_p = out_string;
+	*out_string_p = malloc(sizeof(char) * (str_len + 2));
+	strncpy((*out_string_p) + 1, in_string, str_len);
+	(*out_string_p)[0] = '<';
+	(*out_string_p)[str_len + 1] = '>';
+	(*out_string_p)[str_len + 2] = '\0';
+}
+
+
+void __stdcall DEMODLL tag_string_b(
+	char *in_string,
+	void *out_string
+	)
+{
+	int str_len = strlen(in_string);
+
+	char **out_string_p = out_string;
+	*out_string_p = malloc(sizeof(char) * (str_len + 2));
+	strncpy((*out_string_p) + 1, in_string, str_len);
+	(*out_string_p)[0] = '<';
+	(*out_string_p)[str_len + 1] = '>';
+	(*out_string_p)[str_len + 2] = '\0';
+}
+
+
 float __stdcall DEMODLL simple_demo_routine(
 	float param_a,
 	float param_b
@@ -452,6 +556,85 @@ int16_t __stdcall DEMODLL sum_elements_from_callback_in_struct(
 }
 
 
+int16_t _coordinates_in_image_(
+	image_data *in_image, int16_t x, int16_t y
+	)
+{
+	if(x < 0 || x >= in_image->width || y < 0 || y >= in_image->height){ return 0; }
+	return 1;
+}
+
+
+int16_t _image_pixel_get_(
+	image_data *in_image, int16_t x, int16_t y
+	)
+{
+	if(!_coordinates_in_image_(in_image, x, y)) { return 0; }
+	return in_image->data[(in_image->width * y) + x];
+}
+
+
+void _image_pixel_set_(
+	image_data *in_image, int16_t x, int16_t y, int16_t value
+	)
+{
+	if(!_coordinates_in_image_(in_image, x, y)) { return; }
+	in_image->data[(in_image->width * y) + x] = value;
+}
+
+
+void _image_copy_segment_to_buffer_(
+	image_data *in_image, image_data *in_buffer, int16_t x, int16_t y
+	)
+{
+	int16_t m, n;
+	for(m = 0; m < in_buffer->width; m++)
+	{
+		for(n = 0; n < in_buffer->height; n++)
+		{
+			_image_pixel_set_(in_buffer, m, n, _image_pixel_get_(in_image, x + m, y + n));
+		}
+	}
+}
+
+
+void __stdcall DEMODLL apply_filter_to_image(
+	image_data *in_image,
+	image_data *out_image,
+	filter_func_type filter_func
+	)
+{
+
+	int16_t i, j;
+	const int16_t F_W = 3;
+	const int16_t F_H = 3;
+	const int16_t F_W_off = F_W / 2;
+	const int16_t F_H_off = F_H / 2;
+
+	out_image->data = malloc(sizeof(int16_t) * in_image->width * in_image->height);
+	out_image->width = in_image->width;
+	out_image->height = in_image->height;
+
+	image_data *buffer = malloc(sizeof(image_data));
+	buffer->data = malloc(sizeof(int16_t) * F_W * F_H);
+	buffer->width = F_W;
+	buffer->height = F_H;
+
+	for(i = 0; i < in_image->width; i++)
+	{
+		for(j = 0; j < in_image->height; j++)
+		{
+			_image_copy_segment_to_buffer_(in_image, buffer, i - F_W_off, j - F_H_off);
+			_image_pixel_set_(out_image, i, j, filter_func(buffer));
+		}
+	}
+
+	free(buffer->data);
+	free(buffer);
+
+}
+
+
 int16_t __stdcall DEMODLL use_optional_callback_a(
 	int16_t in_data,
 	conveyor_belt process_data