Command: Start or restart a cog by ID to run Spin code or Propeller Assembly code.

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

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

• CogID is the ID (0 – 7) of the cog to start, or restart. A CogID value of 8 – 15 results in the next available cog being started, if possible; like a COGNEW command.
• SpinMethod is the PUB or PRI Spin method that the affected cog should run. Optionally, it can be followed by a parameter list enclosed in parentheses.
• ParameterList is an optional, comma-delimited list of one or more parameters for SpinMethod. It must be included only if SpinMethod requires parameters.
• StackPointer is a pointer to memory, such as a long array, reserved for stack space for the affected cog. The affected cog uses this space to store temporary data during further calls and expression evaluations. If insufficient space is allocated, either the application will fail to run or it will run with strange results.
• AsmAddress is the address of a Propeller Assembly routine from a DAT block.
• Parameter is used to optionally pass a value to the new cog. This value ends up in the affected cog's read-only Cog Boot Parameter (PAR) register. Parameter can be used to pass a either a single 14-bit value or the address of a block of memory to be used by the assembly routine. Parameter is required by COGINIT, but if not needed for your routine simply set it to an innocuous value like zero (0).

Explanation

COGINIT works exactly like COGNEW 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.

Note that every cog which runs Spin code must have its own stack space; they cannot share the same stack space.

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.