gallant/SDL2
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

wikiheaders: Add a \threadsafety tag to document threading details.

Browse source 
Reference Issue #7140.
This commit is contained in:
Ryan C. Gordon 2023-01-24 22:13:25 -05:00
parent 73dc327c84
commit 01cba48d18
No known key found for this signature in database
GPG key ID: FA148B892AB48044
2 changed files with 43 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

38
build-scripts/wikiheaders.pl
View file

@ -415,6 +415,7 @@ my @standard_wiki_sections = (
'Function Parameters',
'Return Value',
'Remarks',
'Thread Safety',
'Version',
'Code Examples',
'Related Functions'
@ -729,6 +730,7 @@ if ($copy_direction == 1) { # --copy-to-headers
my $remarks = %$sectionsref{'Remarks'};
my $params = %$sectionsref{'Function Parameters'};
my $returns = %$sectionsref{'Return Value'};
my $threadsafety = %$sectionsref{'Thread Safety'};
my $version = %$sectionsref{'Version'};
my $related = %$sectionsref{'Related Functions'};
my $deprecated = %$sectionsref{'Deprecated'};
@ -821,6 +823,21 @@ if ($copy_direction == 1) { # --copy-to-headers
}
}
if (defined $threadsafety) {
# !!! FIXME: lots of code duplication in all of these.
$str .= "\n" if $addblank; $addblank = 1;
my $v = dewikify($wikitype, $threadsafety);
my $whitespacelen = length("\\threadsafety") + 1;
my $whitespace = ' ' x $whitespacelen;
$v = wordwrap($v, -$whitespacelen);
my @desclines = split /\n/, $v;
my $firstline = shift @desclines;
$str .= "\\threadsafety $firstline\n";
foreach (@desclines) {
$str .= "${whitespace}$_\n";
}
}
if (defined $version) {
# !!! FIXME: lots of code duplication in all of these.
$str .= "\n" if $addblank; $addblank = 1;
@ -1047,6 +1064,21 @@ if ($copy_direction == 1) { # --copy-to-headers
}
$desc =~ s/[\s\n]+\Z//ms;
$sections{'Version'} = wordwrap(wikify($wikitype, $desc)) . "\n";
} elsif ($l =~ /\A\\threadsafety\s+(.*)\Z/) {
my $desc = $1;
while (@doxygenlines) {
my $subline = $doxygenlines[0];
$subline =~ s/\A\s*//;
last if $subline =~ /\A\\/; # some sort of doxygen command, assume we're past this thing.
shift @doxygenlines; # dump this line from the array; we're using it.
if ($subline eq '') { # empty line, make sure it keeps the newline char.
$desc .= "\n";
} else {
$desc .= " $subline";
}
}
$desc =~ s/[\s\n]+\Z//ms;
$sections{'Thread Safety'} = wordwrap(wikify($wikitype, $desc)) . "\n";
} elsif ($l =~ /\A\\sa\s+(.*)\Z/) {
my $sa = $1;
$sa =~ s/\(\)\Z//; # Convert "SDL_Func()" to "SDL_Func"
@ -1239,6 +1271,7 @@ if ($copy_direction == 1) { # --copy-to-headers
my $params = %$sectionsref{'Function Parameters'};
my $returns = %$sectionsref{'Return Value'};
my $version = %$sectionsref{'Version'};
my $threadsafety = %$sectionsref{'Thread Safety'};
my $related = %$sectionsref{'Related Functions'};
my $examples = %$sectionsref{'Code Examples'};
my $deprecated = %$sectionsref{'Deprecated'};
@ -1346,6 +1379,11 @@ if ($copy_direction == 1) { # --copy-to-headers
$dewikify_manpage_code_indent = 1;
}
if (defined $threadsafety) {
$str .= ".SH THREAD SAFETY\n";
$str .= dewikify($wikitype, $threadsafety) . "\n";
}
if (defined $version) {
$str .= ".SH AVAILABILITY\n";
$str .= dewikify($wikitype, $version) . "\n";

5
include/SDL3/SDL_render.h
View file

@ -1396,6 +1396,11 @@ extern DECLSPEC int SDLCALL SDL_RenderReadPixels(SDL_Renderer *renderer,
*
* \since This function is available since SDL 3.0.0.
*
* \threadsafety You may only call this function on the main thread. If
* this happens to work on a background thread on any given
* platform or backend, it's purely by luck and you should
* not rely on it to work next time.
*
* \sa SDL_RenderClear
* \sa SDL_RenderLine
* \sa SDL_RenderLines