co.paralleluniverse.pulsar documentation

Pulsar is an implementation of lightweight threads (fibers),
Go-like channles and Erlang-like actors for the JVM

!

macro

(! actor message)(! actor arg & args)
Sends a message to an actor.
This function returns nil.

!!

macro

(!! actor message)(!! actor arg & args)
Sends a message to an actor synchronously.
This has the exact same semantics as ! (in particular, this function always returns nil),
but it hints the scheduler that the current actor is about to wait for a response from the message's addressee.

actor

macro

(actor bindings & body)
Creates a new actor.

as-timeunit

(as-timeunit x)
Converts a keyword to a java.util.concurrent.TimeUnit
<pre>
:nanoseconds | :nanos         -> TimeUnit/NANOSECONDS
:microseconds | :us           -> TimeUnit/MICROSECONDS
:milliseconds | :millis | :ms -> TimeUnit/MILLISECONDS
:seconds | :sec               -> TimeUnit/SECONDS
:minutes | :mins              -> TimeUnit/MINUTES
:hours | :hrs                 -> TimeUnit/HOURS
:days                         -> TimeUnit/DAYS
</pre>

attach!

(attach! channel strand)
Sets a channel's owning strand (fiber or thread).
This is done automatically the first time a rcv (or one of the primitive-type rcv-xxx) is called on the channel.

channel

(channel size)(channel)
Creates a channel

channel-group

(channel-group & channels)
Creates a channel group

current-fiber

(current-fiber)
Returns the currently running lightweight-thread or nil if none

current-strand

(current-strand)
Returns the currently running fiber or current thread in case of new active fiber

defactor

macro

(defactor name doc-string? attr-map? [params*] body)
Defines a new actor template.

defsusfn

macro

(defsusfn & expr)
Defines a suspendable function that can be used by a fiber or actor

double-channel

(double-channel size)(double-channel)
Creates a double channel

fiber

(fiber & args)
Creates a new fiber (a lightweight thread) running in a fork/join pool.

fj-pool

A global fork/join pool. The pool uses all available processors and runs in the async mode.

float-channel

(float-channel size)(float-channel)
Creates a float channel

get-actor

(get-actor a)
If the argument is an actor -- returns it. If not, looks up a registered actor with the argument as its name

int-channel

(int-channel size)(int-channel)
Creates an int channel

link!

(link! actor2)(link! actor1 actor2)
links two actors

long-channel

(long-channel size)(long-channel)
Creates a long channel

mailbox

@mailbox is the mailbox channel of the currently running actor

make-fj-pool

(make-fj-pool parallelism async)
Creates a new ForkJoinPool with the given parallelism and with the given async mode

maketag

(maketag)
Returns a random, probably unique, identifier.
(this is similar to Erlang's makeref).

rcv

(rcv channel)(rcv channel timeout unit)
Receives a message from a channel or a channel group

receive

macro

(receive)(receive patterns* <:after ms action>?)(receive [binding transformation?] patterns* <:after ms action>?)
Receives a message in the current actor and processes it

receive-timed

(receive-timed timeout)
Waits (and returns) for a message for up to timeout ms. If time elapses -- returns nil.

register

(register name actor)(register actor)
Registers an actor

self

@self is the currently running actor

set-state!

(set-state! x)
Sets the state of the currently running actor

snd

(snd channel message)
Sends a message to a channel

spawn

macro

(spawn :name? :mailbox-size? :lifecycle-handler? :stack-size? :pool? f & args)
Creates and starts a new actor

spawn-fiber

macro

(spawn-fiber & args)
Creates and starts a new fiber

spawn-watch

macro

(spawn-watch :name? :mailbox-size? :lifecycle-handler? :stack-size? :pool? f & args)
Creates and starts a new actor, and makes @self monitor it

start

(start fiber)
Starts a fiber

state

@state is the state of the currently running actor

strampoline

(strampoline f)(strampoline f & args)
A suspendable version of trampoline. Should be used to implement
finite-state-machine actors.

trampoline can be used to convert algorithms requiring mutual
recursion without stack consumption. Calls f with supplied args, if
any. If f returns a fn, calls that fn with no arguments, and
continues to repeat, until the return value is not a fn, then
returns that non-fn value. Note that if you want to return a fn as a
final value, you must wrap it in some data structure and unpack it
after trampoline returns.

susfn

macro

(susfn & expr)
Creates a suspendable function that can be used by a fiber or actor

suspendable!

Makes a function suspendable

suspendable?

(suspendable? f)
Returns true of a function has been instrumented as suspendable; false otherwise.

trap!

(trap!)
Sets the current actor to trap lifecycle events (like a dead linked actor) and turn them into messages

unlink!

(unlink! actor2)(unlink! actor1 actor2)
Unlinks two actors

unregister

(unregister x)
Un-registers an actor

unwatch!

(unwatch! actor2 monitor)(unwatch! actor1 actor2 monitor)
Makes an actor stop watch another actor

watch!

(watch! actor2)(watch! actor1 actor2)
Makes an actor watch another actor. Returns a watch object which should be used when calling demonitor.

whereis

(whereis name)
Returns a registered actor by name