[LTP] [PATCH] doc: document tst_checkpoint_create and tst_checkpoint_init

[LTP] [PATCH] doc: document tst_checkpoint_create and tst_checkpoint_init

[Jan Stancek]

Signed-off-by: Jan Stancek <jstancek@redhat.com>
---
 doc/test-writing-guidelines.txt |   16 ++++++++++++++++
 1 files changed, 16 insertions(+), 0 deletions(-)

diff --git a/doc/test-writing-guidelines.txt b/doc/test-writing-guidelines.txt
index 8aaa8b0..67240c2 100644
--- a/doc/test-writing-guidelines.txt
+++ b/doc/test-writing-guidelines.txt
@@ -642,6 +642,22 @@ the same working directory (they use FIFO for synchronization). The checkpoint
 interface provides two pairs of signal and wait functions. One pair to be used
 to signal child from parent and second to signal parent from child.
 
+Checkpoint is represented by 'struct tst_checkpoint', which has to be
+initialized before first usage and FIFO has to be created. This is
+usually done in parent process in single step by calling
+'tst_checkpoint_create()'.
+
+Child processes created via fork() are ready to use tst_checkpoint_*
+synchronization functions, as they inherited already initialized
+'struct tst_checkpoint'.
+
+Child processes started via exec*, or any other process can use already
+created FIFO, provided they initialize 'struct tst_checkpoint' first by
+call to 'tst_checkpoint_init()'. This function does not create any FIFO,
+it relies on fact, that it was already created by some other process.
+Note, that if you use multiple FIFOs in this scenario, these should be
+initialized in same order as in process you are sychronizing against.
+
 For the details of the interface, look into the 'include/tst_checkpoint.h' and
 'lib/tests/tst_checkpoint_*'.
 
-- 
1.7.1


------------------------------------------------------------------------------
Comprehensive Server Monitoring with Site24x7.
Monitor 10 servers for $9/Month.
Get alerted through email, SMS, voice calls or mobile push notifications.
Take corrective actions from your mobile device.
http://p.sf.net/sfu/Zoho
_______________________________________________
Ltp-list mailing list
Ltp-list@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/ltp-list

Re: [LTP] [PATCH] doc: document tst_checkpoint_create and tst_checkpoint_init

[Cyril Hrubis]

Hi!
> @@ -642,6 +642,22 @@ the same working directory (they use FIFO for synchronization). The checkpoint
>  interface provides two pairs of signal and wait functions. One pair to be used
>  to signal child from parent and second to signal parent from child.
>  
> +Checkpoint is represented by 'struct tst_checkpoint', which has to be
> +initialized before first usage and FIFO has to be created. This is
> +usually done in parent process in single step by calling
> +'tst_checkpoint_create()'.
> +
> +Child processes created via fork() are ready to use tst_checkpoint_*
> +synchronization functions, as they inherited already initialized
> +'struct tst_checkpoint'.
> +
> +Child processes started via exec*, or any other process can use already
> +created FIFO, provided they initialize 'struct tst_checkpoint' first by
> +call to 'tst_checkpoint_init()'. This function does not create any FIFO,
> +it relies on fact, that it was already created by some other process.
> +Note, that if you use multiple FIFOs in this scenario, these should be
> +initialized in same order as in process you are sychronizing against.
> +
>  For the details of the interface, look into the 'include/tst_checkpoint.h' and
>  'lib/tests/tst_checkpoint_*'.

Nicely done.

We should also add:

IMPORTANT: Be wary that using single checkpoint to signal child/parent followed
           immediately by wait for parent/child creates an race condtion
	   between opening the pipe and reading from it (the process
	   writing to the fifo may may be the wery same process that
	   reads from it and the checkpoint code will exit the test
	   with error). You are advised to use two checkpoints in this
	   case.

-- 
Cyril Hrubis
chrubis@suse.cz

------------------------------------------------------------------------------
Comprehensive Server Monitoring with Site24x7.
Monitor 10 servers for $9/Month.
Get alerted through email, SMS, voice calls or mobile push notifications.
Take corrective actions from your mobile device.
http://p.sf.net/sfu/Zoho
_______________________________________________
Ltp-list mailing list
Ltp-list@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/ltp-list

Re: [LTP] [PATCH] doc: document tst_checkpoint_create and tst_checkpoint_init

[Cyril Hrubis]

Hi!
> I thought we had this issue only in parent:
> 
> ---------------------------------------------------------------------------------------------------
>                 parent                        |          child
>                                               | tst_checkpoint_child_wait
>                                               |    - has to wait until parent opens pipe for write
> tst_checkpoint_signal_child (NONBLOCK write)  | 
> tst_checkpoint_parent_wait (NONBLOCK read)    |
>   - parent now races on read with child       |
> ---------------------------------------------------------------------------------------------------
> 
> because child is opening always in blocking mode, it will always wait until other
> side is opened as well:
> ---------------------------------------------------------------------------------------------------
>                 parent                        |          child
>                                               | tst_checkpoint_signal_parent
>                                               |    - has to wait until parent opens pipe for read
> tst_checkpoint_parent_wait (NONBLOCK read)    |
>   - reads from FIFO                           |
>                                               | tst_checkpoint_child_wait
>                                               |    - has to wait until parent opens pipe for write
> tst_checkpoint_signal_child (NONBLOCK write)  |   
>   - at this point first byte was already read |
>     from FIFO, parent writes second byte      |
>                                               |    - and only now will child succeed opening pipe
> ---------------------------------------------------------------------------------------------------
> 
> Am I missing something?

You are right. The problem here is that the fifo can be opened for
NONBLOCK reading even if there are no writers and therefore there are
two readers that fight for the data in the fifo.

The second ordering should be fine as far as I can tell.

-- 
Cyril Hrubis
chrubis@suse.cz

------------------------------------------------------------------------------
Comprehensive Server Monitoring with Site24x7.
Monitor 10 servers for $9/Month.
Get alerted through email, SMS, voice calls or mobile push notifications.
Take corrective actions from your mobile device.
http://p.sf.net/sfu/Zoho
_______________________________________________
Ltp-list mailing list
Ltp-list@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/ltp-list