core/docs/persistent_consoles.pod
changeset 0 7f656887cf89
child 64 72ffa331d78d
equal deleted inserted replaced
-1:000000000000 0:7f656887cf89
       
     1 # persistent_consoles.pod
       
     2 #
       
     3 # Copyright (c) 2008-2010 Accenture. All rights reserved.
       
     4 # This component and the accompanying materials are made available
       
     5 # under the terms of the "Eclipse Public License v1.0"
       
     6 # which accompanies this distribution, and is available
       
     7 # at the URL "http://www.eclipse.org/legal/epl-v10.html".
       
     8 #
       
     9 # Initial Contributors:
       
    10 # Accenture - Initial contribution
       
    11 #
       
    12 
       
    13 __END__
       
    14 
       
    15 =head1 Persistent consoles
       
    16 
       
    17 Persistent consoles allow you to maintain a persistent L<fshell|fshell> (or other console application) instance on a device while actual console connections come and go. A persistent console consists of a I<persistent> side, which is owned by a L<fshell|fshell> or other application as its console, and a I<transient> side, which can be connected to or disconnected from another console at any time. This allows you to interact with the persistent console owning application using any console connection available on the device at the time.
       
    18 
       
    19 To illustrate, we can create a new persistent console thus:
       
    20 
       
    21 	c:\>pcons new "my pcons"
       
    22 
       
    23 This create a new, disconnected persistent console. We can use the L<pcons|pcons> command see it:
       
    24 
       
    25 	c:\>pcons list
       
    26 	Name      Creator           Reader  Writer
       
    27 	my pcons  fshell::pcons_00  -       -
       
    28 
       
    29 Note that no reader or writer are attached. We can now connect to the console:
       
    30 
       
    31 	c:\>pcons connect "my pcons"
       
    32 	pcons: connecting to existing console my pcons.
       
    33 	c:\>pcons list
       
    34 	Name         Creator           Reader               Writer
       
    35 	my pcons(*)  fshell::pcons_00  vt100tcpcons_fshell  vt100tcpcons_fshell
       
    36 	(*) indicates current console
       
    37 
       
    38 Now, C<pcons list> shows what I<transient> console the persistent console is connected to - C<vt100tcpcons_fshell>. It also indicates with a C<(*)> the persistent console that we are currently interacting with.
       
    39 
       
    40 If the TCP console we are currently using is disconnected for any reason (perhaps we lost the connection with the device), then the I<transient> side of the console will simply be disconnected and the I<persistent> side will be unaffected. If it tries to interact with the console (perhaps to write some data to it), the call will simply block until we get a new I<transient> side. Hence, after the I<transient> console connection is lost, we can simply reconnect to the same C<fshell> when we are able to re-establish a connection with the device and continue from where we left off, with no state lost.
       
    41 
       
    42 Note, if we exit the C<fshell> session that is connected to the I<persistent> side of the console, the persistent console will be destroyed:
       
    43 
       
    44 	c:\>exit
       
    45 	pcons: disconnected from my pcons
       
    46 	c:\>pcons list
       
    47 	c:\>
       
    48 
       
    49 Hence you should be careful not to exit the C<fshell> session attached to the I<persistent> side of the console if you are relying on the persistency of it to maintain state.
       
    50 
       
    51 We can disconnect the I<transient> side of a persistent console using C<pcons disconnect>:
       
    52 
       
    53 	c:\>pcons disconnect
       
    54 	pcons: disconnected from my pcons
       
    55 	c:\>pcons
       
    56 	Name      Creator           Reader  Writer
       
    57 	my pcons  fshell::pcons_00  -       -
       
    58 	c:\>
       
    59 
       
    60 We can also disconnect a persistent console that we are not currently interacting with by specifying it's name to C<pcons disconnect>.
       
    61 
       
    62 =head2 Creating persistent consoles
       
    63 
       
    64 The above shows the basics of creating a persistent console, however there are several ways of doing this.
       
    65 
       
    66 All L<fshell|fshell> commands support an option C<--persistent-console>, similar to C<--console> but creating a persistent console. For example,
       
    67 
       
    68 	c:\>fshell --persistent-console "fshell_pcons"
       
    69 
       
    70 Note, this call does not return; the new C<fshell> instance is waiting for input on the persistent console, which is currently disconnected. Instead, it may be more useful to use the L<start|start> command to create the new fshell session:
       
    71 
       
    72 	c:\>start fshell --persistent-console "fshell_pcons"
       
    73 	c:\>
       
    74 
       
    75 This creates a new process in the background, which owns a a new persistent console.
       
    76 
       
    77 	c:\>pcons list
       
    78 	Name          Creator           Reader  Writer
       
    79 	my pcons      fshell::pcons_00  -       -
       
    80 	fshell_pcons  fshell(2)         -       -
       
    81 
       
    82 This equivilant to typing C<pcons new fshell_pcons>.
       
    83 
       
    84 You can also specify a process to launch when using C<pcons new> by specifying a command and arguments after the console name. For example,
       
    85 
       
    86 	c:\>pcons new ptf_pcons ptf
       
    87 	c:\>pcons connect ptf_pcons
       
    88 	pcons: connecting to existing console ptf_pcons.
       
    89 	
       
    90 	PromptTestFramework 007d
       
    91 	!>
       
    92 
       
    93 Instead of C<pcons new>, you could have instead used
       
    94 
       
    95 	c:\>start ptf --persistent-console ptf_pcons
       
    96 
       
    97 The L<pcons|pcons> command also supports a C<start> argument, which is similar to C<new>, but with the following semantics:
       
    98 
       
    99 =over
       
   100 
       
   101 =item *
       
   102 
       
   103 If a persistent console with the given name already exists, it will not be created
       
   104 
       
   105 =item *
       
   106 
       
   107 a connection with the named persistent console will be established.
       
   108 
       
   109 =back
       
   110 
       
   111 This can provide a useful shortcut to start interacting with the process attached to the I<persistent> side of the console, creating it if it doesn't already exist. Note, you can specify a command and arguments to C<start> as with C<new>, but these will be ignored if the persistent console already exists.
       
   112 
       
   113 	c:\>pcons start "my pcons"
       
   114 	pcons: connecting to existing console my pcons.
       
   115 	c:\>
       
   116 	
       
   117 	c:\>pcons start "new pcons"
       
   118 	pcons: connecting to new console new pcons.
       
   119 	c:\>
       
   120 
       
   121 =head2 Connecting other consoles
       
   122 
       
   123 You can use C<pcons connect> to connect a new console as the I<transient> side by using the C<--console> option:
       
   124 
       
   125 	c:\>pcons connect "my pcons" --console vt100tcpcons
       
   126 
       
   127 This will create a new console implementation of the type specified and connect it to the persistent console.
       
   128 
       
   129 As stated earlier, when a persistent consoles I<transient> side is disconnected, any operations on it will block. This will generally cause the process connected to the I<persistent> side to lock up until a real console implementation is connected. If you want to allow this process to run, without blocking while no I<transient> console is connected, you can connect it to the null console:
       
   130 
       
   131 	c:\>pcons connect "my pcons" --console nullcons
       
   132 
       
   133 This cause all output written by the persistent process to be discarded, and hence allow the process to run while no console is connected to the device.
       
   134 
       
   135 =head1 Copyright
       
   136 
       
   137 Copyright (c) 2009-2010 Accenture. All rights reserved.
       
   138 
       
   139 =cut