GraphicsMagick: Add some documentation regarding OpenMP
GraphicsMagick Commits <[email protected]>
| Newsgroups | gmane.comp.video.graphicsmagick.cvs |
|---|---|
| Message-ID | <mailman.10208.1688162806.1565.graphicsmagick-commit@lists.sourceforge.net> |
changeset cca2c405d50e in /hg/GraphicsMagick details: http://hg.GraphicsMagick.org/hg/GraphicsMagick?cmd=changeset;node=cca2c405d50e summary: Add some documentation regarding OpenMP diffstat: ChangeLog | 2 ++ magick/magick.c | 27 ++++++++++++++++++++------- www/Changelog.html | 1 + www/api/magick.html | 22 ++++++++++++++++------ 4 files changed, 39 insertions(+), 13 deletions(-) diffs (138 lines): diff -r 36ee33717a61 -r cca2c405d50e ChangeLog --- a/ChangeLog Fri Jun 30 15:30:02 2023 -0500 +++ b/ChangeLog Fri Jun 30 17:06:30 2023 -0500 @@ -1,5 +1,7 @@ 2023-06-30 Bob Friesenhahn <[email protected]> + * magick/magick.c: Add some documentation regarding OpenMP. + * coders/tga.c (LogTGAInfo): Avoid compiler warning about orientation possibly being undefined. Update source code to conform to common style. diff -r 36ee33717a61 -r cca2c405d50e magick/magick.c --- a/magick/magick.c Fri Jun 30 15:30:02 2023 -0500 +++ b/magick/magick.c Fri Jun 30 17:06:30 2023 -0500 @@ -1,5 +1,5 @@ /* -% Copyright (C) 2003-2022 GraphicsMagick Group +% Copyright (C) 2003-2023 GraphicsMagick Group % Copyright (C) 2002 ImageMagick Studio % Copyright 1991-1999 E. I. du Pont de Nemours and Company % @@ -146,10 +146,18 @@ % should be invoked in the primary (original) thread of the application's % process while shutting down, and only after any threads which might be % using GraphicsMagick functions have terminated. Since GraphicsMagick -% uses threads internally via OpenMP, it is also necessary for any function -% calls into GraphicsMagick to have already returned so that OpenMP worker -% threads are quiesced and won't be accessing any semaphores or data -% structures which are destroyed by this function. +% may use threads internally via OpenMP, it is also necessary for any +% function calls into GraphicsMagick to have already returned so that +% OpenMP worker threads are quiesced and won't be accessing any semaphores +% or data structures which are destroyed by this function. +% +% The OpenMP implementation (if present) starts/stops any OpenMP worker +% threads and allocates/frees OpenMP resources using its own algorithms. +% This means that OpenMP worker threads and OpenMP resources are likely +% to remain allocated after DestroyMagick() returns. Since OpenMP 5.0, +% invoking omp_pause_resource_all(omp_pause_hard) will assure that any +% resources allocated by OpenMP (threads, thread-specific memory, etc.) +% are freed, and this may be called after DestroyMagick() has returned. % % The format of the DestroyMagick function is: % @@ -1128,7 +1136,8 @@ % % InitializeMagickEx() initializes the GraphicsMagick environment, % providing a bit more more control and visibility over initialization -% than the original InitializeMagick(). +% than the original InitializeMagick(). Use DestroyMagick() to destroy +% the GraphicsMagick environment when it is not longer needed. % % InitializeMagick() or InitializeMagickEx() MUST be invoked by the using % program before making use of GraphicsMagick functions or else the library @@ -1142,6 +1151,10 @@ % then that function should be invoked before InitializeMagickEx() since % the memory allocation functions need to be consistent. % +% Available options are: +% +% o MAGICK_OPT_NO_SIGNAL_HANDER - Don't register ANSI/POSIX signal handlers +% % The format of the InitializeMagickEx function is: % % MagickPassFail InitializeMagickEx(const char *path, @@ -1152,7 +1165,7 @@ % % o path: The execution path of the current GraphicsMagick client (or NULL) % -% o options: Options flags tailoring initializations performed +% o options: Options bit flags tailoring initializations performed % % o exception: Information about initialization failure is reported here. % diff -r 36ee33717a61 -r cca2c405d50e www/Changelog.html --- a/www/Changelog.html Fri Jun 30 15:30:02 2023 -0500 +++ b/www/Changelog.html Fri Jun 30 17:06:30 2023 -0500 @@ -40,6 +40,7 @@ <p>2023-06-30 Bob Friesenhahn <<a class="reference external" href="mailto:bfriesen%40simple.dallas.tx.us">bfriesen<span>@</span>simple<span>.</span>dallas<span>.</span>tx<span>.</span>us</a>></p> <blockquote> <ul class="simple"> +<li><p>magick/magick.c: Add some documentation regarding OpenMP.</p></li> <li><p>coders/tga.c (LogTGAInfo): Avoid compiler warning about orientation possibly being undefined. Update source code to conform to common style.</p></li> diff -r 36ee33717a61 -r cca2c405d50e www/api/magick.html --- a/www/api/magick.html Fri Jun 30 15:30:02 2023 -0500 +++ b/www/api/magick.html Fri Jun 30 17:06:30 2023 -0500 @@ -73,10 +73,17 @@ should be invoked in the primary (original) thread of the application's process while shutting down, and only after any threads which might be using GraphicsMagick functions have terminated. Since GraphicsMagick -uses threads internally via OpenMP, it is also necessary for any function -calls into GraphicsMagick to have already returned so that OpenMP worker -threads are quiesced and won't be accessing any semaphores or data -structures which are destroyed by this function.</p> +may use threads internally via OpenMP, it is also necessary for any +function calls into GraphicsMagick to have already returned so that +OpenMP worker threads are quiesced and won't be accessing any semaphores +or data structures which are destroyed by this function.</p> +<p>The OpenMP implementation (if present) starts/stops any OpenMP worker +threads and allocates/frees OpenMP resources using its own algorithms. +This means that OpenMP worker threads and OpenMP resources are likely +to remain allocated after DestroyMagick() returns. Since OpenMP 5.0, +invoking omp_pause_resource_all(omp_pause_hard) will assure that any +resources allocated by OpenMP (threads, thread-specific memory, etc.) +are freed, and this may be called after DestroyMagick() has returned.</p> <p>The format of the DestroyMagick function is:</p> <pre class="literal-block">DestroyMagick( void );</pre> </div> @@ -223,7 +230,8 @@ <h2>Description</h2> <p>InitializeMagickEx() initializes the GraphicsMagick environment, providing a bit more more control and visibility over initialization -than the original InitializeMagick().</p> +than the original InitializeMagick(). Use DestroyMagick() to destroy +the GraphicsMagick environment when it is not longer needed.</p> <p>InitializeMagick() or InitializeMagickEx() MUST be invoked by the using program before making use of GraphicsMagick functions or else the library will be unusable and any usage is likely to cause a crash.</p> @@ -233,6 +241,8 @@ <p>If alternate memory allocations are provided via MagickAllocFunctions() then that function should be invoked before InitializeMagickEx() since the memory allocation functions need to be consistent.</p> +<p>Available options are:</p> +<p>o MAGICK_OPT_NO_SIGNAL_HANDER - Don't register ANSI/POSIX signal handlers</p> <p>The format of the InitializeMagickEx function is:</p> <pre class="literal-block">MagickPassFail InitializeMagickEx( const char *path, unsigned int options, <a class="reference external" href="../api/types.html#exceptioninfo">ExceptionInfo</a> *exception );</pre> @@ -241,7 +251,7 @@ <dd><p>The execution path of the current GraphicsMagick client (or NULL)</p> </dd> <dt>options:</dt> -<dd><p>Options flags tailoring initializations performed</p> +<dd><p>Options bit flags tailoring initializations performed</p> </dd> <dt>exception:</dt> <dd><p>Information about initialization failure is reported here.</p>