... when referring to a function's parameter or a struct/union's
member.
The idea of using FOO comes from the GNU coding standards:
The comment on a function is much clearer if you use the argument
names to speak about the argument values. The variable name
itself should be lower case, but write it in upper case when you
are speaking about the value rather than the variable itself.
Thus, "the inode number NODE_NUM" rather than "an inode".
Upcasing names is problematic for a case-sensitive language like C,
because it can create ambiguity. Moreover, it's too much shouting for
my taste.
GTK-Doc's convention to prefix the identifier with @ makes references
to variables stand out nicely. The rest of the GTK-Doc conventions
make no sense for us, however.
Signed-off-by: Markus Armbruster <armbru@pond.sub.org>
Why upgrade? I'm not a lawyer, but here's my take on the differences
to version 2:
* Software patents: better protection against abuse of patents to
prevent users from exercising the rights under the GPL. I doubt
we'll get hit with a patent suit, but it's a good move just on
general principles.
* License compatibility: compatible with more free licenses, i.e. can
"steal" more free software for use in Empire. I don't expect to steal
much, but it's nice to have the option.
* Definition of "source code": modernization of some details for today's
networked world, to make it easier to distribute the software. Not
really relevant to us now, as we normally distribute full source code.
* Tivoization: this is about putting GPL-licensed software in hardware,
then make the hardware refuse to run modified software. "Neat" trick
to effectively deny its users their rights under the GPL. Abuse was
"pioneered" by TiVo (popular digital video recorders). GPLv3 forbids
it. Unlikely to become a problem for us.
* Internationalization: more careful wording, to harden the license
outside the US. The lawyers tell us it better be done that way.
* License violations: friendlier way to deal with license violations.
This has come out of past experience enforcing the GPL.
* Additional permissions: Probably not relevant to us.
Also include myself in the list of principal authors.
LWP and Windows implementations already did that. Rewrite the
pthreads implementation.
The write-bias makes the stupid play_wrlock_wanted busy wait in
dispatch() unnecessary. Remove it.
pthread.c's empth_select() returned -1 when empth_wakeup() interrupted
select(). The failure then got propagated all the way up, and the
player got logged out. Fix by returning 0 in that case. While there,
retry on EINTR, to match LWP. Also clarify comments.
Unused since 4.3.10. Can be used safely only in very special
circumstances.
Removal allows simplifying pthread.c and ntthread.c some. liblwp left
alone.
Remove the KillIdle thread. Add timeout to struct iop, initialized in
io_open(). Obey it in io_input() by passing it to empth_select(). If
empth_select() times out, report that back through io_input() to
recvclient() and player_login(). If player_login() receives a timeout
indication, print a message and terminate the session. If
recvclient() receives a timeout indication, flash a message to the
player and initiate a shut down the player's session.
Create WIN32 sys/time.h to define struct timeval. This creates some
conflicts with WIN32 windows.h definitions. Including windows.h in
show.c and info.c creates conflicts, so remove that. Modify service.c
to include sys/socket.h instead of windows.h to remove the conflict
with sys/time.h.
supports priorities. Update synchronization used to rely on them,
which naturally worked only with LWP (#1504036). With that fixed, no
uses of priorities remained, but a minor bug did: players could starve
out threads with priorities below PP_PLAYER, i.e. delete_lostitems()
and player_kill_idle(). Closes#1458175:
(empth_create): Remove parameter prio. Callers changed. Also gets
rid of misleading comments in pthread.c and ntthread.c.
(PP_MAIN, PP_UPDATE, PP_SHUTDOWN, PP_SCHED, PP_TIMESTAMP, PP_PLAYER)
(PP_ACCEPT, PP_KILLIDLE): Remove.
(empth_init, empth_create) [EMPTH_LWP]: Pass priority 1.
empth_sleep() return whether that happened:
[EMPTH_LWP] (lwpWakeupSleep): New, factored out of lwpSelect().
[EMPTH_LWP] (lwpSelect): Use it.
[EMPTH_LWP] (lwpWakeup): New. Call lwpWakeupFd() if sleeping in
lwpSleepFd(), lwpWakeupSleep() if sleeping in lwpSleepUntil().
[EMPTH_LWP] (lwpTerminate, empth_wakeup): Use it rather than
lwpWakeupFd().
[EMPTH_LWP] (lwpWakeupFd): Internal linkage.
[EMPTH_LWP] (lwpSleepUntil): Reset member runtime, so that lwpWakeup()
can test it reliably. Return how sleep woke up.
[EMPTH_LWP] (empth_sleep): Return value of lwpSleepUntil().
[EMPTH_POSIX] (EMPTH_INTR): New.
[EMPTH_POSIX] (empth_wakeup): Set state to it.
[EMPTH_POSIX] (empth_restorectx): Clear state.
[EMPTH_POSIX] (empth_sleep): Don't re-seleep when state is not clear,
i.e. thread was woken up prematurely. Return how sleep woke up.
[EMPTH_W32] (empth_sleep): Implement by waiting on hThreadEvent with a
timeout rather than a straight Sleep(). Return how sleep woke up.
other. Ensure headers in include/ can be included in any order
(except for econfig-spec.h, which is special). New header types.h to
help avoid inclusion cycles. Sort include directives. Remove some
superflous includes.
(keep_journal): New econfig key.
(player_main): Log player login and logout.
(recvclient): Log player input.
(ef_open_srv, ef_close_srv): Log startup and shutdown.
(update_main): Log update.
Support the common SIGHUP log rotation idiom:
(empth_wait_for_shutdown, empth_wait_for_signal): Rename.
[EMPTH_LWP, EMPTH_POSIX] (empth_init, empth_wait_for_signal): Wait for
SIGHUP as well.
(main) [SIGHUP]: Reopen journal when empth_wait_for_signal() returns
SIGHUP.
(empth_wait_for_shutdown): New.
(main): Use it to wait for shutdown signal, then shut down. Closes
#770492.
(empth_exit): Remove the weird special case for main thread.
Implement empth_wait_for_shutdown() for EMPTH_LWP:
[EMPTH_LWP] (lwpInitSigWait, lwpSigWait, lwpSigWakeup): New.
Declaration of lwpSigWait was accidentally committed in the previous
revision of lwp.h.
[EMPTH_LWP] (lwpInitSystem): New parameter waitset, pass it on to
lwpInitSigWait().
[EMPTH_LWP] (lwpReschedule): Call lwpSigWakeup().
[EMPTH_LWP] (empth_init): Declare signals needed by
empth_wait_for_shutdown().
(empth_wait_for_shutdown): Implement on top of lwpSigWait().
Implement empth_wait_for_shutdown() for EMPTH_POSIX:
[EMPTH_POSIX] (empth_init): Block signals, so that
empth_wait_for_shutdown() can use sigwait() safely.
(empth_wait_for_shutdown): Implement on top of sigwait().
Implement empth_wait_for_shutdown() for EMPTH_W32:
(empth_wait_for_shutdown): Implement on top of loc_BlockMainThread().
(empth_init_signals): New, factored out of start_server(). Call from
empth_init().
(panic): Move to posix.c, internal linkage.
(empth_obj): Add new posix.o
(empth_start, empth_alarm) [EMPTH_POSIX]: Clean up pointless messing
with signal handlers.
(empth_init, empth_wakeup) [EMPTH_POSIX]: Clean up a bit.
compiler command line. Don't bother to conditionalize code in .c
files that are only compiled when their thread package is used.
(_EMPTH_LWP, EMPTH_LWP, _EMPTH_POSIX, EMPTH_POSIX, _EMPTH_WIN32)
(EMPTH_W32): Identifiers beginning with an underscore and an uppercase
letter are reserved for any use. Rename.
