...

((PUB ┆ PRI))
  COGINIT (CogID, SpinMethod  < (ParameterList) >, StackPointer )

...

((PUB ┆ PRI))
  COGINIT (CogID, AsmAddress, Parameter )

...

COGINIT works exactly like COGNEW (page ) with two exceptions: 1) it launches code into a specific cog whose ID is CogID, and 2) it does not return a value. Since COGINIT operates on a specific cog, as directed by the CogID parameter, it can be used to stop and restart an active cog in one step. This includes the current cog; i.e., a cog can use COGINIT to stop and restart itself to run, perhaps, completely different code.

...

In addition, care must be taken when relaunching a cog with Spin code and specifying stack space that is currently in use by that cog. The Propeller always builds a cog's initial stack frame in the specified stack space before launching the cog. Relaunching a cog with a COGINIT command specifying the same stack space that it is currently using will likely cause the new stack frame image to be clobbered before the cog is restarted. To prevent this from happening, first perform a COGSTOP on that cog, followed by the desired COGINIT.

Spin Code (Syntax 1)

To run a Spin method in a specific cog, the COGINIT command needs the cog ID, the method name, its parameters, and a pointer to some stack space. For example:

coginit(1, Square(@X), @SqStack)      'Launch Square in Cog 1 

This example launches the Square method into Cog 1, passing the address of X into Square and the address of SqStack as COGINIT's stack pointer. See COGNEW for more information.

Propeller Assembly Code (Syntax 2)

To run Propeller Assembly code in a specific cog, the COGINIT command needs the cog ID, the address of the assembly routine, and a value that can optionally be used by the assembly routine. For example:

coginit(2, @Toggle, 0)

This example launches the Propeller Assembly routine, Toggle, into Cog 2 with a PAR parameter of 0. See the example in the assembly syntax description of COGNEW for a more detailed example keeping in mind that the above COGINIT command can be used in place of COGNEW in that example.

The Parameter Field

It's important to note that the Parameter field is intended to pass a long address, so only 14 bits (bits 2 through 15) are passed into the cog's PAR register; the lower two bits are always cleared to zero to ensure it's a long-aligned address. A value other than a long address can still be passed via the Parameter field, but will have to be limited to 14 bits, must be shifted left by two bits (for the COGNEW/COGINIT command), and will have to be shifted right by two bits by the assembly program that receives it.