Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 171 lines (136 sloc) 6.995 kb
c2eb2ea Added formatting to the readme.
Kevin Malakoff authored
1 ````
2 _ _ _ _
3 | |__ __ _ ___| | ____ _ _ __ ___ _ _ _ __ __| | (_)___
4 | '_ \ / _` |/ __| |/ / _` | '__/ _ \| | | | '_ \ / _` | | / __|
5 | |_) | (_| | (__| < (_| | | | (_) | |_| | | | | (_| |_ | \__ \
6 |_.__/ \__,_|\___|_|\_\__, |_| \___/ \__,_|_| |_|\__,_(_)/ |___/
7 |___/ |__/
8 ````
9
10 Background.js provides a background job queue and list with array iterators for Javascript applications.
11
12 You can get the library here:
13
14 * Development version: https://github.com/kmalakoff/background/raw/master/background.js
15 * Production version: https://github.com/kmalakoff/background/raw/master/background.min.js
16
17 # An Example:
18
19 ````
20 queue = new Background.JobQueue(10) # create a queue that processes each 10 milliseconds
21 iterator = null # declare the iterator here so it is available in the init and run loop
22 test_array1 = [3,7,11]; test_array2 = [3,5]; test_array3 = [13,3,23]
23 iteration_count = 0; result = 0
24
25 queue.push(
26 (->
27 # set up the iterator for the arrays in batches of 3
28 iterator = new Background.ArrayIterator_xN([test_array1,test_array2,test_array3],3)
29 ),
30 (->
31 iteration_count++
32 return iterator.nextByItems((items)-> result += items[0]*items[1]*items[2])
33 ),
34 (->
35 # use the result here, push another job onto the queue, etc
36 )
37 )
38 ````
39
40 # Classes:
41
42 ## Background.JobQueue
43 A sequentially-processed background job queue. When you 'push' a job on a queue, it is run on each 'tick' until it signals it is finished then the job that was added immediately after is run on the next 'tick' until it has completed...and so on.
44
45 ## Background.JobList
46 A sequentially-processed background job list. When you 'append' a job on a list, it and the rest of the jobs in the list are run on each 'tick' in the order they were appended until they signal that they are done.
47
48 ## Background.ArrayIterator
49 A helper to iterate over a subset of an array on each 'tick'. You can either process the subset per iteration:
50
51 * callback per array item - by calling 'nextByItem' with a function of the form: (item) -> do_something
52 * callback per array slice - by calling 'nextBySlice' with a function of the form: (slice) -> do_something
53 * callback per range (of type Background.Range)- by calling 'nextByRange' with a function of the form: (range) -> do_something
54 * manually using step() which returns a range (of type Background.Range) and isDone() after manually processing the range
55
56 ## Background.Range
57 A single array range iterator which is used per iteration to access array items. Public interfaces:
58
59 * isDone(): returns boolean indicating whether the iteration is complete or you need to keep calling step()
60 * step(): keeps stepping through indices until done
61 * getItem(array): used to get the item that the range iterator is currently referring to
62 * getSlice(array): used to get all the items that the range is referring to
63
64 ## Background.ArrayIterator_xN
65 A helper to iterate over a collection of arrays on each 'tick'. It is used to iterate through all combinations between the given arrays in equal steps on each tick; for example, you can apply M transformations to each of N elements giving N*M operations in arbitrary equal sized batches per tick. You can either process the subset per iteration:
66
67 * callback per array item - by calling 'nextByItems' with a function of the form: (items_array) -> do_something
68 * callback per array combinations - by calling 'nextByCombinations' with a function of the form: (combinations) -> do_something
69 * callback per range (of type Background.Range_xN) - by calling 'nextByRange' with a function of the form: (range) -> do_something
70 * manually using step() which returns a range (of type Background.Range_xN) and isDone() after manually processing the range
71
72 ## Background.Range_xN
73 A multiple array range iterator which is used per iteration to access array items. Public interfaces:
74
75 * isDone(): returns boolean indicating whether the iteration is complete or you need to keep calling step()
76 * step(): keeps stepping through indices until done
77 * getItems(arrays): used to get the items that all of the range iterators are currently referring to
78 * getCombinations(arrays): used to get all the pair combinations of the arrays items that the range is referring to
79
80 ## Background.Job
81 A job class which requires a run_fn and can optionally be provided an init_fn and/or a destroy_fn.
82
83 # Tips
84
85 1) You can manually call 'tick' instead of waiting for the background timer.
86 2) You can 'destroy' a job queue or list and it will cancel all of the jobs, and will mark it as destroyed.
87 3) You can 'clear' a job queue or list and it will cancel all of the jobs.
88 4) You can 'push' or 'append' a job without using the Background.Job class by just passing the functions directly. In other words,
89 'my_list.append(null, ->)' is equivalent to 'my_list.append(new Background.Job(null, ->))'.
90
91 Please look at the provided examples and specs for sample code:
92
93 * https://github.com/kmalakoff/background/blob/master/examples/src/example_queue.coffee
94 * https://github.com/kmalakoff/background/blob/master/examples/src/example_list.coffee
95 * https://github.com/kmalakoff/background/blob/master/spec
96
97
98 # Background on Background.js
99 This library was originally based on the following project: https://github.com/infojunkie/JobQueue with the following enhancements:
100
292bdfd Tweaked README.
Kevin Malakoff authored
101 ### Allow the caller to provide set up and clean up functions:
c2eb2ea Added formatting to the readme.
Kevin Malakoff authored
102
292bdfd Tweaked README.
Kevin Malakoff authored
103 * Job without setup and cleanup:
8ebcc8d One more tweak.
Kevin Malakoff authored
104
c2eb2ea Added formatting to the readme.
Kevin Malakoff authored
105 ````
106 job_queue = new Background.JobQueue(10) # timeslice of 10ms per iteration
107 job_queue.push(
108 null,
109 (->
110 return true # done
111 )
112 )
113 ````
114
292bdfd Tweaked README.
Kevin Malakoff authored
115 * Job with setup and cleanup:
8ebcc8d One more tweak.
Kevin Malakoff authored
116
c2eb2ea Added formatting to the readme.
Kevin Malakoff authored
117 ````
118 some_var = false
119 job_queue = new Background.JobQueue(10) # timeslice of 10ms per iteration
120 job_queue.push(
121 (->some_var=1),
122 (->
123 return true # done
124 ),
125 ((was_completed)->some_var=true)
126 )
127 ````
128
292bdfd Tweaked README.
Kevin Malakoff authored
129 ### The addition of an array iterator
c2eb2ea Added formatting to the readme.
Kevin Malakoff authored
130
292bdfd Tweaked README.
Kevin Malakoff authored
131 * Iterate by array item per timeslice
c2eb2ea Added formatting to the readme.
Kevin Malakoff authored
132
133 ````
134 some_data = [1, 2, 3, 4]
135 iterator = null
136 job_queue = new Background.JobQueue(10) # timeslice of 10ms per iteration
137 job_queue.push(
138 (->
139 iterator = new Background.ArrayIterator(some_data, 2) # process 2 items per job timeslice
140 ),
141 (-> return iterator.nextByItem((item) ->) ),
142 )
143 ````
144
292bdfd Tweaked README.
Kevin Malakoff authored
145 * Iterate by array slice per timeslice
8ebcc8d One more tweak.
Kevin Malakoff authored
146
c2eb2ea Added formatting to the readme.
Kevin Malakoff authored
147 ````
148 some_data = [1, 2, 3, 4]
149 iterator = null
150 job_queue = new Background.JobQueue(10) # timeslice of 10ms per iteration
151 job_queue.push(
152 (->
153 iterator = new Background.ArrayIterator(some_data, 2) # process 2 items per job timeslice
154 ),
155 (-> return iterator.nextBySlice((items) ->) ),
156 )
157 ````
158
292bdfd Tweaked README.
Kevin Malakoff authored
159 ### Allow the caller to destroy the queue (for example, if you have a single page app)
c2eb2ea Added formatting to the readme.
Kevin Malakoff authored
160 ````
161 was_destroyed = false
162 job_queue = new Background.JobQueue(10) # timeslice of 10ms per iteration
163 job_queue.push(
164 null,
165 (->
166 return false # not done
167 ),
168 ((was_completed)->was_destroyed=(was_completed==false))
169 )
170 job_queue.destroy(); job_queue = null
171 ````
Something went wrong with that request. Please try again.