View lcov test coverage results on http://www.ufoot.org/liquidwar/v6/doc/coverage/src/lib/pil/index.html.
sys_context: global system context
argc: number of args as passed to main
argv: args passed to main
bench_result: pointer to float, will contain the bench result
progress: to inform the caller of the process advancement
Runs a standard, normalized bench on a default map. Results can be interpreted as an estimated speed/power of your computer.
Return value: 1 on success, 0 if failure
sys_context: global system context
command_text: readable text of the command
seq_0: sequence offset reference (to calculate difference between sequence and rounds)
round_0: round offset reference (to calculate difference between sequence and rounds)
Creates a new command from its text representation.
Return value: newly allocated object
sys_context: global system context
command: object to duplicate
Creates a copy of a command struct.
Return value: newly allocated object.
sys_context: global system context
command: command to free
Frees a command struct, with all its members.
Return value: none.
sys_context: global system context
command: command to represent
Gives a readable representation of a command.
Return value: dynamically allocated string.
sys_context: global system context
dump: pointer on dump structure (out param, can be NULL)
timestamp: current timestamp (can be 0 if dump is NULL)
game_state: game state to work on, can be NULL (usefull for DUMP)
command: command to process
Interprets a command and runs it against game_state. If dump and timestamp are set, then any DUMP command will fill the dump structure with the right values. If not running from a pilot context, this is useless, use NULL and 0LL.
Return value: 1 if ok, 0 if failed.
sys_context: global system context
dump: pointer on dump structure (out param, can be NULL)
timestamp: current timestamp (can be 0 if dump is NULL)
game_state: game state to work on, can be NULL (typically for DUMP)
command_text: command text to process
seq_0: reference seq_0, used to genereate consistent dumps if needed
Interprets a command text and runs it against game_state. If dump and timestamp are set, then any DUMP command will fill the dump structure with the right values. If not running from a pilot context, this is useless, use NULL and 0LL.
Return value: 1 if ok, 0 if failed.
sys_context: global system context
local_cursors: local cursors information
command: command to execute
Executes a local command, typically a cursor move, on the local_cursor struct, without changing any game state.
Return value: 1 if success, 0 if failure.
sys_context: global system context
local_cursors: local cursors information
command_text: command text to execute
Executes a local command text, typically a cursor move, on the local_cursor struct, without changing any game state.
Return value: 1 if success, 0 if failure.
sys_context: global system context
rules: the set of rules to use (defines polarity)
shape: the shape of the map (logical part)
x: the x coord to fix
y: the y coord to fix
z: the z coord to fix
Similar to lw6map_coords_fix but using floats, this function
can be used to check cursor position boundaries. Any float pointer
can be NULL.
Return value: none.
sys_context: global system context
rules: the set of rules to use (defines polarity)
shape: the shape of the map (logical part)
x: the x coord to fix
y: the y coord to fix
z: the z coord to fix
Similar to lw6pil_coords_fix but does use a wider range, say 10 times
the actual size of the map, this is not to contain the cursor within
the map but just to avoid overflow errors.
Return value: none.
sys_context: global system context
dump: object to initialize
Fills a dump object with zero, regardless of what was there before.
Return value: none.
sys_context: global system context
dump: object to clear
Clears a dump object, that is, frees all existing object if they are here, and sets pointers to NULL.
Return value: none.
sys_context: global system context
dump: object to test
Tests wether there’s actually a dump in the structure, or if it’s empty.
Return value: 1 if there’s a dump, 0 if all fields set to NULL.
sys_context: global system context
pilot: the pilot to transform as a DUMP.
server_id: ID of server issuing the command
seq: seq at which the dump should be generated
Creates the DUMP command for a given pilot, that is, a command that describes the whole data and state. One must give a sequence number since the dump would otherwise typically be *always* late by at least one round (or seq). We give the seq as we would for any message generated, to make it fit well within the standard message queue.
Return value: newly allocated string
sys_context: global system context
dump: will contain the dump data, pilot and game state, struct, and level
timestamp: current timestamp
command: the command to execute
progress: progress object to show the advancement of process
Interprets a DUMP command. A new pilot will be returned, along with game state, game struct and level. Old objects won’t be deleted, but you could (should) get rid of them at they are useless now.
Return value: newly allocated string
sys_context: global system context
local_cursors: the structure to reset
Resets a local cursors struct. Note that this need not be called very often, in fact the local cursors can cope with "dead" cursors easily. In practise, in a local game, there are only 4 of them, great maximum.
Return value: none.
sys_context: global system context
local_cursors: the structure to query
cursor_id: the id of the cursor to query
Returns a pointer on the cursor with the given id.
Return value: a pointer (must *not* be freed) which is NULL is cursor does not exist.
local_cursors: the structure to query
x: a pointer to the x position, may be NULL
y: a pointer to the y position, may be NULL
mouse_controlled: a pointer to the mouse_controlled flag, may be NULL
cursor_id: the id of the cursor to query
Gets the x,y position of the cursor, and tells if it’s mouse controlled.
Return value: 1 on success (cursor exists), 0 on failure (no such cursor).
sys_context: global system context
local_cursors: the structure to modify
cursor_id: the id of the cursor to modify
x: the x position
y: the y position
Sets the position of a cursor in the local cursors struct. If cursor does not exists, it’s appended to the list.
Return value: 1 on success (cursor exists), 0 on failure (no such cursor).
sys_context: global system context
local_cursors: the structure to modify
cursor_id: the id of the cursor to modify
mouse_controlled: the mouse_controlled attribute
Sets which cursor is mouse controlled. If mouse_controlled is 1, the flag is set for this cursor and cleared for all others. If set to 0, only this cursor’s flag is cleared.
Return value: 1 on success (cursor exists), 0 on failure (no such cursor).
sys_context: global system context
local_cursors: the structure to query
cursor_id: the id of the main cursor, may be NULL
x: a pointer to the x position, may be NULL
y: a pointer to the y position, may be NULL
mouse_controlled: a pointer to the mouse_controlled flag, may be NULL
Gets the x,y position of the main cursor, and tells if it’s mouse controlled.
Return value: 1 on success (cursor exists), 0 on failure (no such cursor).
sys_context: global system context
local_cursors: the structure to modify
cursor_id: the id of the cursor to be labelled as main cursor
Sets the main cursor attribute, the main cursor is later used, for instance, to decide how to display the map (centered on it, for instance).
Return value: 1 on success (cursor exists), 0 on failure (no such cursor).
sys_context: global system context
dump: will contain the dump information if needed, can be NULL
command_text: the command received from the network.
timestamp: timestamp, used to initialize the pilot
Normally, it’s the commit function of the pilot which will automatically return a dump if needed. But... when a client connects, at first, it has absolutely no pilot/map whatsoever yet, so this is just to bootstrap the process, this function will take network messages, any message, and if it’s about a dump -> it will create the dump.
Return value: 1 on success, 0 on failure.
sys_context: global system context
game_state: the game state we’re going to work on
seq_0: the start sequence to use, that is, the seq at round=0
timestamp: the current ticks (1000 ticks per sec, used to calibrate)
progress: object used to show the advancement of the process
Initializes a ’pilot’ object, this object is responsible for interpreting messages, transform them into low-level ’ker’ module function calls, and handle all the thread-spooky stuff.
Return value: a working pilot object. May be NULL on memory failure.
sys_context: global system context
pilot: the object to free.
Frees a ’pilot’ object, note that this might involve joining some threads, so it can ’take some time’.
Return value: none.
sys_context: global system context
pilot: the object to send commands to.
command_text: the text of the command, as received form network
verified: wether we’re sure this message is valid.
Sends a command and handles it internally.
Return value: 1 if OK, 0 if not.
sys_context: global system context
pilot: the object to apply the local command on
command_text: the command text
This function is used to fix the annoying fact that by only sending commands a limited number of times per sec to the game state, the display always reflect an outdated position for cursors. But players do not want to see this, they want to see the cursor in the right place. So what we do is that the pilot can process "local" commands which have absolutely no effect on the game but simply update a local cursor state, only used for display. It’s here in the pil module for it’s where the command interpreting code is, and the fact that there’s this lag is directly linked with the pilot way of doing things.
Return value: 1 on success, 0 on failure.
sys_context: global system context
dump: will contain the dump information if needed, can be NULL
pilot: the object to commit.
Commits all commands sent and actually send them to the corresponding threads. This commit system allows better performance by sending, for instance, all the commands for a given round together.
Return value: none.
sys_context: global system context
pilot: the object to perform the backup on
Makes a new backup in the pilot, that is, copy ’reference’ to ’backup’.
Return value: 1 if OK, 0 if not.
sys_context: global system context
target: the target game_state we would sync on
pilot: the object to perform the backup on
Tests wether sync functions are callable with a given game state. It verifies if the internal game_state and the target look the same.
Return value: 1 if sync functions can be called, 0 if not.
sys_context: global system context
target: the game_state structure which will get the informations.
pilot: the object to get informations from.
Gets the backup from the pilot object. This is the last snapshot
taken by make_backup or, by default, the game_state the pilot
was constructed with.
Return value: 1 if OK, 0 if not.
sys_context: global system context
target: the game_state structure which will get the informations.
pilot: the object to get informations from.
Gets the latest reference game_state, that is, a stable snapshot of the game, with no inconsistency, a game position that exists and that we can rely on. Note that getting this can take time since a global mutex is required, and computations must end before you get the data.
Return value: 1 if OK, 0 if not.
sys_context: global system context
target: the game_state structure which will get the informations.
pilot: the object to get informations from.
dirty_read: wether to allow dirty read or not
Gets the informations from the pilot object, not being worried about game consistency, this one will just return the latest version available. It might even be in an inconsistent state, the position could reflect a position which will never exist. Still, the data returned will not correspond to a half-spread or half-moved game_state if dirty_read is set to 0. In this case the data has at least some basic consistency and getting this does require some mutex lock, however wait time should be fairly small (max. a round). But, in a general manner, this function is only used for display, and we do not care much if there’s a small glitch, we prefer fast & smooth display.
Return value: 1 if OK, 0 if not.
sys_context: global system context
pilot: the object to get informations from.
Returns a direct access to the most up-to-date game_state, without locking anything whatsoever. This is clearly to implement a dirty read mode as the name of the function suggests.
Return value: 1 if OK, 0 if not.
sys_context: global system context
Returns a string describing the pilot. This is a very short description, use it for logs, and to debug stuff. By no means it’s a complete exhaustive description. Still, the string returned should be unique.
Return value: a dynamically allocated string.
sys_context: global system context
pilot: the object to calibrate
timestamp: the current ticks setting (1000 ticks per second)
seq: the round expected to be returned with this ticks value
Calibrates the pilot, that is, initializes it so that subsequent calls
to lw6pil_pilot_get_round return consistent values.
Return value: none.
sys_context: global system context
pilot: the pilot to speed up
seq_inc: the number of seqs
Re-calibrates the pilot so that it speeds up a bit. This will basically increase next_seq by seq_inc.
Return value: none.
sys_context: global system context
pilot: the pilot to speed up
seq_dec: the number of seqs
Re-calibrates the pilot so that it slows down a bit. This will basically decrease next_seq by seq_inc.
Return value: none.
sys_context: global system context
pilot: pilot object to query
Get the initial round (the one passed at object construction) which says what the round was at object creation, it’s just an offset.
Return value: 64-bit integer
sys_context: global system context
pilot: pilot object to query
Get the initial seq (the one passed at object construction) which says what the seq was at round=0, it’s just an offset.
Return value: 64-bit integer
sys_context: global system context
pilot: pilot object to work on
seq: the seq to convert
Converts a seq (64-bit) to a round (32-bit). 64-bit seqs are used to avoid out-of-range errors on very long games, OTOH a round is 32-bit to garantee the atomicity of its affection, even on platforms which are not native 64-bit.
Return value: the round (32-bit integer)
sys_context: global system context
pilot: pilot object to work on
round: the round to convert
Converts a round (32-bit) to a seq (64-bit). 64-bit seqs are used to avoid out-of-range errors on very long games, OTOH a round is 32-bit to garantee the atomicity of its affection, even on platforms which are not native 64-bit.
Return value: the seq (64-bit integer)
sys_context: global system context
pilot: the object to query
timestamp: the current ticks setting (1000 ticks per second)
Returns the seq one should use to generate new events/commands at a given time (given in ticks).
Return value: none.
sys_context: global system context
pilot: the object to query
Returns the seq of the last commit (reference game_state) for this object.
Return value: the commit seq (reference object)
sys_context: global system context
pilot: the object to query
Returns the seq which is targetted in the reference game_state, this is ’how far computation will go in the reference game_state if no new commands are issued’. Note that there can always be some commands which are not yet processed, so you should not rely on this too heavily, however it gives a good idea of how things are going.
Return value: the target seq (reference object)
sys_context: global system context
pilot: the object to query
Returns the current seq in the reference game_state. There’s no lock on this call so don’t rely on this too heavily, it just gives you an idea of wether the pilot is very late on its objectives or just on time.
Return value: the current seq (reference object)
sys_context: global system context
pilot: the object to query
Returns the max current seq in the reference or draft game states. No lock on this call so don’t rely on this too heavily, it just gives you an idea of computation state.
Return value: the current seq (reference object)
sys_context: global system context
pilot: the object to query
Tells wether the game is over or not.
Return value: 1 if over, 0 if not
sys_context: global system context
pilot: the object to query
cursor_id: the cursor_id concerned
Tells wether a given cursor was winner or not.
Return value: 1 if over, 0 if not
sys_context: global system context
pilot: the object to query
Gets the winner color.
Return value: a team color, -1 if no winner and/or error.
sys_context: global system context
pilot: the object to query
Gets the looser color.
Return value: a team color, -1 if no looser and/or error.
sys_context: global system context
pilot: object to query
Returns a pointer on the local_cursors struct used within the object. Beware, this is the *real* pointer, not a copy...
Return value: pointer on internal object
sys_context: global system context
pilot: the pilot to track
checksum_log_interval: dump interval, if 0, feature is disabled
Debugging function used to set automatically an interval at which engine will log a checksum automatically. This is typically to track down where and when there starts to be a difference between two game_states that have evolved separately. This function will propagate the parameter to all the game_states handled by the pilot, each will log its informations separately.
Return value: none
sys_context: global system context
pilot: the pilot to transform as a SEED.
server_id: ID of server issuing the command
seq: seq at which the dump should be generated
Creates the SEED command for a given pilot, that is, a command that contains macro informations about the game state such as current seq. It should be followed by a dump.
Return value: newly allocated string
sys_context: global system context
Gets a pseudo-random start seq, why do we use this? Just to make sure even in non-network situations, seq are always very high and random, this way this is one less bug to check in networked context.
Return value: random integer value, always greater than INT_MAX
sys_context: global system context
dump: dump to use as a base to init the suite (out param)
timestamp: timestamp used for pilot creation (should be "now")
Build the objects used by the test suite. The idea is to wrap all this in a single function since it requires to be exactly the same every time as the test suite is very pedantic about checksums.
Return value: 1 on success, 0 on failure.
sys_context: global system context
Get the base seq_0 for the reference test suite.
Return value: 64-bit integer.
sys_context: global system context
node_index: index of the node we want informations about
Get the node_id associated to an index, typically a 64-bit unique. The index is just a simple integer which is 0 for node A, 1 for node B, etc.
Return value: the node id, as an unsigned 64-bit integer
sys_context: global system context
node_index: index of the node (not its id)
stage: major stage of the test suite
step: minor step of the test suite
Get the reference test suite message by node_index, stage and step.
Return value: static string, must not be freed.
sys_context: global system context
stage: major stage of the test suite
step: minor step of the test suite
Get the reference test suite message by stage and step. Messages from various nodes are mixed and sorted.
Return value: static string, must not be freed.
sys_context: global system context
step: minor step of the test suite
Get the reference test suite message by step. Messages from various nodes and stages are mixed and sorted.
Return value: static string, must not be freed.
sys_context: global system context
game_state_checksum: expected checksum for the given checkpoint (out param)
seq: expected seq for the given checkpoint (out param)
round: expected round for the given checkpoint (out param)
stage: stage to query checksum and other info about
Gives the values which are expected for a given checkpoint. If the right messages have been feeded, then these values are expected.
Return value: none, everything in out params
sys_context: global system context
mode: test mode (bitmask)
Registers all tests for the libpil module.
Return value: 1 if test is successfull, 0 on error.
sys_context: global system context
mode: test mode (bitmask)
Runs the pil module test suite, testing most (if not all...)
functions.
Return value: 1 if test is successfull, 0 on error.
Arguments passed to the ADD command.
Type: u_int16_t
Definition: u_int16_t lw6pil_add_args_s::cursor_id
Cursor ID (16-bit non-zero unsigned int).
Type: int
Definition: int lw6pil_add_args_s::team_color
Team color (0 to 9).
Command structure, contains both full-text version and parsed information.
Type: int64_t
Definition: int64_t lw6pil_command_s::seq
The sequence number, a very large 64-bit integer. The sequence is here because the round wouldn’t be able to stand multiple games for long as it is only 32-bit. OTOH making round a 64-bit would cause multithread problems because of non-atomicity of 64-bit affectation on truely 32-bit platforms.
Type: int
Definition: int lw6pil_command_s::round
The game round.
Type: u_int64_t
Definition: u_int64_t lw6pil_command_s::node_id
The node ID issuing that command.
Type: lw6pil_command_code_t
Definition: lw6pil_command_code_t lw6pil_command_s::code
The command code.
Type: lw6pil_command_args_t
Definition: lw6pil_command_args_t lw6pil_command_s::args
The command arguments, parsed.
Type: char *
Definition: char* lw6pil_command_s::text
The original full text of the command.
Arguments passed to the DUMP command.
Type: char *
Definition: char* lw6pil_dump_args_s::level_hexa
Hexa dump of level.
Type: char *
Definition: char* lw6pil_dump_args_s::game_struct_hexa
Hexa dump of game struct.
Type: char *
Definition: char* lw6pil_dump_args_s::game_state_hexa
Hexa dump of game state.
Stores the information contained in a dump, this is just an utility struct used to hold all the data (level, game struct, game state and pilot) together
Type: lw6map_level_t *
Definition: lw6map_level_t* lw6pil_dump_s::level
Will hold the new level if a dump is received.
Type: lw6ker_game_struct_t *
Definition: lw6ker_game_struct_t* lw6pil_dump_s::game_struct
Will hold the new game struct if a dump is received.
Type: lw6ker_game_state_t *
Definition: lw6ker_game_state_t* lw6pil_dump_s::game_state
Will hold the new game state if a dump is received.
Type: lw6pil_pilot_p
Definition: lw6pil_pilot_p lw6pil_dump_s::pilot
Will hold the new pilot if a dump is received.
Contains information about all local cursors, which will override information from game state.
Type: u_int16_t
Definition: u_int16_t lw6pil_local_cursors_s::main_cursor_id
Main cursor ID (16-bit non-zero unsigned int). By main, we usually mean the mouse-driven one but necessarily. But still, this is a cursor which will have a special role, it will be used to center the map if needed, among other things.
Type: int
Definition: int lw6pil_local_cursors_s::main_i
Main cursor index.
Type: int
Definition: int lw6pil_local_cursors_s::nb_cursors
Number of cursors.
Type: lw6pil_local_cursor_t
Definition: lw6pil_local_cursor_t lw6pil_local_cursors_s::cursors[LW6MAP_MAX_NB_CURSORS]
The cursors array.
Stores informations about local cursors. This is usefull for user feedback. Indeed there can be some delay between, for instance, a mouse move or a keyboard press, and the time this information makes it through the whole pipeline. Players wouldn’t understand such a lag so for local cursors we override the information from the game state with that information we get right from the GUI.
Type: u_int16_t
Definition: u_int16_t lw6pil_local_cursor_s::cursor_id
Cursor ID (16-bit non-zero unsigned int).
Type: int
Definition: int lw6pil_local_cursor_s::x
X position (map coords).
Type: int
Definition: int lw6pil_local_cursor_s::y
Y position (map coords).
Type: int
Definition: int lw6pil_local_cursor_s::mouse_controlled
Wether this cursor is mouse controlled. If yes, then information will be taken directly from the mouse driver.
Type: int
Definition: int lw6pil_local_cursor_s::is_main
Wether this cursor is the main cursor.
Pilot is a container for several game states, a reference state which we can rely upon and a draft state which is anticipated to provide interactive feedback but reflects non-validated informations. The first member, id, is the same as the internal _lw6pil_pilot_t structure. The rest of it is hidden. The program will cast from lw6pil_pilot_t to _lw6pil_pilot_t internally.
Type: u_int32_t
Definition: u_int32_t lw6pil_pilot_s::id
The id of the object, this is non-zero and unique within one run session, incremented at each object creation.
Arguments passed to the REMOVE command.
Type: u_int16_t
Definition: u_int16_t lw6pil_remove_args_s::cursor_id
Cursor ID (16-bit non-zero unsigned int).
Arguments passed to the SET command.
Type: u_int64_t
Definition: u_int64_t lw6pil_set_args_s::cursor_id
Cursor ID (16-bit non-zero unsigned int).
Type: int
Definition: int lw6pil_set_args_s::x
X position (map coords).
Type: int
Definition: int lw6pil_set_args_s::y
Y position (map coords).
Type: int
Definition: int lw6pil_set_args_s::fire
Wether to activate primary weapon.
Type: int
Definition: int lw6pil_set_args_s::fire2
Wether to activate secondary weapon.
Worker thread data, used to calculate stuff in a separate thread. The principle is simple, it tries to keep up with a given target round, whenever this round isn’t reached, it computes more and more rounds.
Type: int
Definition: volatile int lw6pil_worker_s::run
Wether this thread should run, 0 will stop it.
Type: int
Definition: int lw6pil_worker_s::verified
Wether this is running in verified mode or not.
Type: int
Definition: volatile int lw6pil_worker_s::current_round
Current game round.
Type: int
Definition: volatile int lw6pil_worker_s::target_round
Round up to which we should compute stuff.
Type: int
Definition: volatile int lw6pil_worker_s::computed_rounds
How many rounds where computed since object creation.
Type: int
Definition: volatile int lw6pil_worker_s::over
Wether the game is over or not.
Type: lw6sys_thread_handler_t *
Definition: lw6sys_thread_handler_t* lw6pil_worker_s::compute_thread
The thread that does the job.
Type: lw6sys_mutex_t *
Definition: lw6sys_mutex_t* lw6pil_worker_s::global_mutex
Global data mutex.
Type: lw6sys_mutex_t *
Definition: lw6sys_mutex_t* lw6pil_worker_s::compute_mutex
Mutex used for the computing thread.
Type: lw6ker_game_state_t *
Definition: lw6ker_game_state_t* lw6pil_worker_s::game_state
Game state the computing thread is working on.
Type: lw6sys_list_r_t *
Definition: lw6sys_list_r_t* lw6pil_worker_s::commands
List of commands to be processed.
Type: lw6pil_dump_t
Definition: lw6pil_dump_t lw6pil_worker_s::dump
Dump information.
Arguments passed to various commands.
Type: lw6pil_add_args_t
Definition: lw6pil_add_args_t lw6pil_command_args_u::add
Arguments when command is ADD.
Type: lw6pil_remove_args_t
Definition: lw6pil_remove_args_t lw6pil_command_args_u::remove
Arguments when command is REMOVE.
Type: lw6pil_set_args_t
Definition: lw6pil_set_args_t lw6pil_command_args_u::set
Arguments when command is SET.
Type: lw6pil_dump_args_t
Definition: lw6pil_dump_args_t lw6pil_command_args_u::dump
Arguments when command is DUMP.